@ecsia/scheduler 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Aragon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @ecsia/scheduler
+
+The frame scheduler for [**ecsia**](https://github.com/andymai/ecsia) — a fast, type-safe Entity
+Component System for TypeScript.
+
+`@ecsia/scheduler` derives an access-graph conflict DAG from each system's declared
+`{read, write}` set, runs the resulting waves, and — opt-in — dispatches disjoint-write work
+across a real `worker_threads` + `Atomics` pool whose result is **bit-identical** to the
+serial path (a fixed worker-index command-buffer merge makes the merge order deterministic).
+
+> **Status:** 0.1.0, unpublished. Most users want the umbrella package
+> [`ecsia`](https://www.npmjs.com/package/ecsia), which re-exports `defineSystem`,
+> `createScheduler`, and `WorkerPool`.
+>
+> **Known limitation (worker pool):** the pool is `node:worker_threads`-based and requires
+> `SharedArrayBuffer`; without it, ecsia warns and runs single-threaded — never silently.
+> A browser Web-Worker pool is future work.
+
+## Install
+
+```sh
+pnpm add @ecsia/scheduler @ecsia/core   # not yet published — local workspace for now
+```
+
+## Links
+
+- Repository & full docs: https://github.com/andymai/ecsia
+- Umbrella package: [`ecsia`](https://github.com/andymai/ecsia)
+
+## License
+
+[MIT](./LICENSE) © Andy Aragon

package/dist/commands/apply.d.ts

@@ -0,0 +1,49 @@
+import { Op } from './op.js';
+import type { CommandBuffer } from './buffer.js';
+import type { ComponentFieldCodec } from './fields.js';
+import type { ComponentDef, ComponentId, RelationId, Schema } from '@ecsia/schema';
+import type { EntityHandle } from '@ecsia/core';
+/** A staged structural intent (legacy seam, kept for compatibility). */
+export interface StructuralIntent {
+    readonly op: Op;
+}
+export interface CommandSink {
+    flushAll(): void;
+}
+/** The single-thread sink: structural ops never deferred, so the flush is empty work. */
+export declare const directApplySink: CommandSink;
+/**
+ * The main-thread world verbs the apply path drives. Built from the World's
+ * public surface by the scheduler. Every call runs serial/main-thread (PHASE-2 flush slot).
+ */
+export interface WorldApply {
+    isAlive(h: EntityHandle): boolean;
+    handleIndex(h: EntityHandle): number;
+    /** Place an already-reserved (alive) handle into the EMPTY archetype + emit Create. */
+    spawnReserved(h: EntityHandle): void;
+    despawn(h: EntityHandle): void;
+    /** id → registered ComponentDef (for migration + write-view). */
+    defOf(id: ComponentId): ComponentDef<Schema> | undefined;
+    /** Field codec for a component id (payload decode). */
+    codecOf(id: ComponentId): ComponentFieldCodec | undefined;
+    /** One migration adding several components. */
+    addMany(h: EntityHandle, defs: readonly ComponentDef<Schema>[]): void;
+    removeMany(h: EntityHandle, defs: readonly ComponentDef<Schema>[]): void;
+    /** Is `def` currently present on `h`? (SET_PAYLOAD requires presence). */
+    has(h: EntityHandle, def: ComponentDef<Schema>): boolean;
+    /** Write decoded field values into `h`'s current row + emit the `.changed` write-log entry. */
+    writePayload(h: EntityHandle, def: ComponentDef<Schema>, values: Record<string, unknown>): void;
+    /** Reclaim the unconsumed reservation tail after this worker's creates are applied. */
+    returnUnused(cb: CommandBuffer): void;
+    /** Relation apply (best-effort; relations land at ). */
+    addPair?(subject: EntityHandle, relationId: RelationId, target: EntityHandle, payload: Record<string, unknown> | undefined): void;
+    removePair?(subject: EntityHandle, relationId: RelationId, target: EntityHandle): void;
+    warn(message: string): void;
+}
+/**
+ * Apply every worker's command buffer to the world in fixed worker-index order. `world.phase` MUST be
+ * 'serial' (the scheduler flips it back before calling this). Returns the number of records applied
+ * (diagnostics).
+ */
+export declare function flushAll(world: WorldApply, buffers: readonly CommandBuffer[]): void;
+//# sourceMappingURL=apply.d.ts.map

package/dist/commands/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/commands/apply.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,EAAE,EAAa,MAAM,SAAS,CAAA;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAElF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAI/C,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,IAAI,IAAI,CAAA;CACjB;AAED,yFAAyF;AACzF,eAAO,MAAM,eAAe,EAAE,WAI7B,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAAA;IACjC,WAAW,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAAA;IACpC,uFAAuF;IACvF,aAAa,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IACpC,OAAO,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IAC9B,iEAAiE;IACjE,KAAK,CAAC,EAAE,EAAE,WAAW,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IACxD,uDAAuD;IACvD,OAAO,CAAC,EAAE,EAAE,WAAW,GAAG,mBAAmB,GAAG,SAAS,CAAA;IACzD,+CAA+C;IAC/C,OAAO,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAA;IACrE,UAAU,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAA;IACxE,0EAA0E;IAC1E,GAAG,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,OAAO,CAAA;IACxD,+FAA+F;IAC/F,YAAY,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC/F,uFAAuF;IACvF,YAAY,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAAA;IACrC,wDAAwD;IACxD,OAAO,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,CAAA;IACjI,UAAU,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;IACtF,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAoBD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,CAQnF"}

package/dist/commands/apply.js

@@ -0,0 +1,211 @@
+// Command-buffer flush + deterministic merge + validate-then-apply.
+// The main thread merges every worker's buffer in FIXED worker-index order, applies each record
+// serially (validate-then-apply, drop-if-dead with an in-flush tombstone set), coalesces per-entity
+// adds/removes into ONE migration each, and returns unused reserved ids. This is what makes a
+// multi-worker run SERIAL-EQUIVALENT to the single-threaded executor: encoding order across workers is
+// nondeterministic, but applying order is fixed (ascending worker index, then append order).
+import { Op, recordLen } from './op.js';
+import { NO_ENTITY } from '@ecsia/core';
+const NO_ENTITY_BITS = NO_ENTITY >>> 0;
+/** The single-thread sink: structural ops never deferred, so the flush is empty work. */
+export const directApplySink = {
+    flushAll() {
+        // Zero workers → zero command buffers → no-op.
+    },
+};
+function newPending() {
+    return { adds: [], removes: [], payloads: new Map() };
+}
+function pushUnique(arr, c) {
+    if (!arr.includes(c))
+        arr.push(c);
+}
+function removeFrom(arr, c) {
+    const i = arr.indexOf(c);
+    if (i >= 0)
+        arr.splice(i, 1);
+}
+/**
+ * Apply every worker's command buffer to the world in fixed worker-index order. `world.phase` MUST be
+ * 'serial' (the scheduler flips it back before calling this). Returns the number of records applied
+ * (diagnostics).
+ */
+export function flushAll(world, buffers) {
+    const newlyCreated = new Set(); // (by handle bit-pattern)
+    const tombstones = new Set(); //
+    // Ascending workerIndex is the deterministic merge order. Buffers are passed in index order
+    // by the caller; sort defensively so the invariant holds regardless of array order.
+    const ordered = [...buffers].sort((a, b) => a.workerIndex - b.workerIndex);
+    for (const cb of ordered)
+        applyBuffer(world, cb, newlyCreated, tombstones);
+    for (const cb of ordered)
+        world.returnUnused(cb);
+}
+function validateSubject(world, h, newlyCreated, tombstones) {
+    if (newlyCreated.has(h))
+        return true; // reserved-and-created THIS flush → alive
+    if (tombstones.has(world.handleIndex(h))) {
+        world.warn(`command references entity destroyed earlier this flush (handle ${h})`);
+        return false;
+    }
+    if (!world.isAlive(h)) {
+        world.warn(`command references dead entity (handle ${h})`);
+        return false;
+    }
+    return true;
+}
+function applyBuffer(world, cb, newlyCreated, tombstones) {
+    const pending = new Map();
+    const words = cb.words;
+    let at = 0;
+    let appliedCreates = 0;
+    const drain = (h) => {
+        const p = pending.get(h);
+        if (p === undefined)
+            return;
+        // removes before adds so a remove-then-add of distinct ids lands in the final archetype.
+        if (p.removes.length > 0) {
+            const defs = p.removes.map((c) => world.defOf(c)).filter((d) => d !== undefined);
+            if (defs.length > 0)
+                world.removeMany(h, defs);
+        }
+        if (p.adds.length > 0) {
+            const defs = p.adds.map((c) => world.defOf(c)).filter((d) => d !== undefined);
+            if (defs.length > 0)
+                world.addMany(h, defs);
+        }
+        for (const [cid, values] of p.payloads) {
+            const def = world.defOf(cid);
+            if (def !== undefined)
+                world.writePayload(h, def, values);
+        }
+        pending.delete(h);
+    };
+    while (at < cb.head) {
+        const op = words[at];
+        const len = recordLen(words, at);
+        switch (op) {
+            case Op.CREATE: {
+                const h = words[at + 1];
+                // Belt-and-suspenders: a reserved handle is ALWAYS alive, so a
+                // well-formed OP_CREATE never names NO_ENTITY. Guard anyway so a corrupt/exhaustion-fabricated
+                // record can never reach spawnReserved(0xffffffff) → handleIndex(NO_ENTITY) → record-table
+                // corruption. Dropped: emits nothing, not counted toward appliedCreates (no reservation slot
+                // was consumed for it).
+                if (h >>> 0 === NO_ENTITY_BITS) {
+                    world.warn('OP_CREATE names NO_ENTITY (reservation exhausted upstream); dropped');
+                    break;
+                }
+                world.spawnReserved(h);
+                newlyCreated.add(h);
+                appliedCreates += 1;
+                break;
+            }
+            case Op.DESTROY: {
+                const h = words[at + 1];
+                if (validateSubject(world, h, newlyCreated, tombstones)) {
+                    drain(h); // flush any pending structure before the entity disappears
+                    world.despawn(h);
+                    tombstones.add(world.handleIndex(h));
+                }
+                break;
+            }
+            case Op.ADD: {
+                const h = words[at + 1];
+                const cid = words[at + 2];
+                const f = words[at + 3];
+                if (validateSubject(world, h, newlyCreated, tombstones)) {
+                    const p = pending.get(h) ?? setPending(pending, h);
+                    removeFrom(p.removes, cid);
+                    pushUnique(p.adds, cid);
+                    if (f > 0) {
+                        const codec = world.codecOf(cid);
+                        if (codec !== undefined)
+                            p.payloads.set(cid, codec.decode(words, at + 4));
+                    }
+                }
+                break;
+            }
+            case Op.REMOVE: {
+                const h = words[at + 1];
+                const cid = words[at + 2];
+                if (validateSubject(world, h, newlyCreated, tombstones)) {
+                    const p = pending.get(h) ?? setPending(pending, h);
+                    removeFrom(p.adds, cid);
+                    pushUnique(p.removes, cid);
+                    p.payloads.delete(cid);
+                }
+                break;
+            }
+            case Op.SET_PAYLOAD: {
+                const h = words[at + 1];
+                const cid = words[at + 2];
+                if (validateSubject(world, h, newlyCreated, tombstones)) {
+                    const codec = world.codecOf(cid);
+                    const def = world.defOf(cid);
+                    if (codec !== undefined && def !== undefined) {
+                        const values = codec.decode(words, at + 4);
+                        const p = pending.get(h);
+                        if (p !== undefined && p.adds.includes(cid)) {
+                            p.payloads.set(cid, values); // fold into the add's payload
+                        }
+                        else {
+                            drain(h); // ensure the component is present at its current row before overwriting
+                            if (world.has(h, def))
+                                world.writePayload(h, def, values);
+                            else
+                                world.warn(`SET_PAYLOAD on absent component (handle ${h}, id ${cid})`);
+                        }
+                    }
+                }
+                break;
+            }
+            case Op.ADD_PAIR: {
+                const s = words[at + 1];
+                const rid = words[at + 2];
+                const t = words[at + 3];
+                // ADD_PAIR drops if EITHER subject or target is dead (a relation to a
+                // destroyed target is meaningless). Both go through the drop-if-dead gate.
+                if (validateSubject(world, s, newlyCreated, tombstones) &&
+                    validateSubject(world, t, newlyCreated, tombstones)) {
+                    drain(s);
+                    if (world.addPair !== undefined) {
+                        // Worker-path pair PAYLOADS are deferred — the worker encoder
+                        // emits payloadWordCount=0 (no relation-schema replication yet), so there are no payload
+                        // words to decode and the pair is applied with an undefined payload. recordLen() still skips
+                        // the (zero) payload words correctly. The pair/presence/back-ref/mint are all applied.
+                        world.addPair(s, rid, t, undefined);
+                    }
+                    else {
+                        world.warn('ADD_PAIR encountered but relations are not wired');
+                    }
+                }
+                break;
+            }
+            case Op.REMOVE_PAIR: {
+                const s = words[at + 1];
+                const rid = words[at + 2];
+                const t = words[at + 3];
+                if (validateSubject(world, s, newlyCreated, tombstones)) {
+                    drain(s);
+                    if (world.removePair !== undefined)
+                        world.removePair(s, rid, t);
+                }
+                break;
+            }
+            default:
+                throw new Error(`corrupt command buffer: bad opcode ${op} at ${at}`);
+        }
+        at += len;
+    }
+    // Drain any entity still pending at end-of-buffer.
+    for (const key of [...pending.keys()])
+        drain(key);
+    cb.appliedCreateCount = appliedCreates;
+}
+function setPending(map, h) {
+    const p = newPending();
+    map.set(h, p);
+    return p;
+}
+//# sourceMappingURL=apply.js.map

package/dist/commands/apply.js.map

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

package/dist/commands/buffer.d.ts

@@ -0,0 +1,53 @@
+import type { EntityHandle, EntityReservation } from '@ecsia/core';
+/** A per-worker reservation block consumed by OP_CREATE. */
+export interface BufferReservation {
+    readonly handles: readonly EntityHandle[];
+}
+export interface CommandBuffer {
+    /** Worker index this buffer belongs to (0..workers-1). Fixes merge order. */
+    readonly workerIndex: number;
+    /** u32 words. SAB-backed in the threaded path, plain AB in the fallback. */
+    words: Uint32Array;
+    /** Write head: index of the next free u32 slot. Reset to 0 each wave. */
+    head: number;
+    /** Count of records appended this wave (diagnostics / merge bound). */
+    recordCount: number;
+    /** The worker's reservation block for this wave. Consumed by OP_CREATE in append order. */
+    reservation: BufferReservation;
+    /** Cursor into `reservation.handles`: next unused reserved handle. */
+    reservationCursor: number;
+    /** Count of OP_CREATE records actually applied (set by the apply path for returnUnused). */
+    appliedCreateCount: number;
+    /** The EntityReservation block reserved for this buffer's wave (main-thread bookkeeping for ). */
+    lastReservation?: EntityReservation;
+    /**
+     * When true the backing is a FIXED-SIZE SharedArrayBuffer that MUST NOT be reassigned mid-wave: the
+     * main thread reads records in place over the same SAB, so growing the worker-side view off the SAB
+     * would point `head` past the shared backing and either lose records or corrupt the apply decode
+     * (review issue #3). On a fixed buffer `ensureWords` caps instead of growing and sets `overflowed`.
+     */
+    fixed: boolean;
+    /** Set by `ensureWords` when a fixed (SAB) buffer could not fit a record: encoding was capped. */
+    overflowed: boolean;
+    /** Latch so the encoder emits the overflow diagnostic ONCE per wave; cleared by `resetBuffer`. */
+    overflowWarned?: boolean;
+}
+export declare function makeCommandBuffer(workerIndex: number, initialWords: number, shared: boolean): CommandBuffer;
+/**: head→0, retain backing. Steady-state encoding is allocation-free. */
+export declare function resetBuffer(cb: CommandBuffer): void;
+/**
+ *: ensure room for `need` more words. Returns true iff the caller may now write
+ * `need` words at `cb.head`.
+ *
+ * Plain-AB (growable) buffers double on overflow and always return true — the no-sab
+ * transport reads `{ words, head }` after the fence so a reallocated private buffer is fine.
+ *
+ * FIXED (SAB-backed) buffers MUST NOT reassign `cb.words` off the shared backing (review issue #3): the
+ * main thread reads the same SAB in place up to `head`, so a worker-private grow would (a) hide the
+ * overflow records from the main thread and (b) push `head` past the SAB length → NaN-opcode crash in
+ * `recordLen`. Instead we CAP: set `overflowed`, leave `head` untouched, and return false so the encoder
+ * appends NOTHING. The buffer therefore always satisfies `head <= words.length`, and the overflow is a
+ * loud diagnostic rather than silent loss + crash.
+ */
+export declare function ensureWords(cb: CommandBuffer, need: number): boolean;
+//# sourceMappingURL=buffer.d.ts.map

package/dist/commands/buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../src/commands/buffer.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAElE,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAA;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,4EAA4E;IAC5E,KAAK,EAAE,WAAW,CAAA;IAClB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAA;IACnB,2FAA2F;IAC3F,WAAW,EAAE,iBAAiB,CAAA;IAC9B,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,CAAA;IACzB,4FAA4F;IAC5F,kBAAkB,EAAE,MAAM,CAAA;IAC1B,kGAAkG;IAClG,eAAe,CAAC,EAAE,iBAAiB,CAAA;IACnC;;;;;OAKG;IACH,KAAK,EAAE,OAAO,CAAA;IACd,kGAAkG;IAClG,UAAU,EAAE,OAAO,CAAA;IACnB,kGAAkG;IAClG,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAID,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,aAAa,CAe3G;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAOnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAYpE"}

package/dist/commands/buffer.js

@@ -0,0 +1,66 @@
+// Per-worker command buffer: a plain (or SAB-backed) Uint32Array a worker
+// appends structural-intent records into mid-wave and the main thread replays at the serial flush.
+//
+// Backing choice: the buffer is written ONLY by its owning worker and read
+// ONLY by the main thread AFTER the wave fence — no concurrent access ever — so no atomics are needed
+// on it. In the SAB/Atomics runtime we back it with a *fixed-size* SharedArrayBuffer so the main
+// thread reads the worker's records in place (no per-flush transfer); growth past that cap spills to
+// a plain-AB overflow which the worker reports back via its `head`. In the
+// postMessage fallback the backing is a plain ArrayBuffer transferred at flush. Either way the apply
+// path (apply.ts) reads `{ words, head }` byte-for-byte identically.
+const EMPTY_RESERVATION = { handles: [] };
+export function makeCommandBuffer(workerIndex, initialWords, shared) {
+    const bytes = Math.max(initialWords, 16) * 4;
+    const backing = shared ? new SharedArrayBuffer(bytes) : new ArrayBuffer(bytes);
+    return {
+        workerIndex,
+        words: new Uint32Array(backing),
+        head: 0,
+        recordCount: 0,
+        reservation: EMPTY_RESERVATION,
+        reservationCursor: 0,
+        appliedCreateCount: 0,
+        fixed: shared,
+        overflowed: false,
+        overflowWarned: false,
+    };
+}
+/**: head→0, retain backing. Steady-state encoding is allocation-free. */
+export function resetBuffer(cb) {
+    cb.head = 0;
+    cb.recordCount = 0;
+    cb.reservationCursor = 0;
+    cb.appliedCreateCount = 0;
+    cb.overflowed = false;
+    cb.overflowWarned = false;
+}
+/**
+ *: ensure room for `need` more words. Returns true iff the caller may now write
+ * `need` words at `cb.head`.
+ *
+ * Plain-AB (growable) buffers double on overflow and always return true — the no-sab
+ * transport reads `{ words, head }` after the fence so a reallocated private buffer is fine.
+ *
+ * FIXED (SAB-backed) buffers MUST NOT reassign `cb.words` off the shared backing (review issue #3): the
+ * main thread reads the same SAB in place up to `head`, so a worker-private grow would (a) hide the
+ * overflow records from the main thread and (b) push `head` past the SAB length → NaN-opcode crash in
+ * `recordLen`. Instead we CAP: set `overflowed`, leave `head` untouched, and return false so the encoder
+ * appends NOTHING. The buffer therefore always satisfies `head <= words.length`, and the overflow is a
+ * loud diagnostic rather than silent loss + crash.
+ */
+export function ensureWords(cb, need) {
+    if (cb.head + need <= cb.words.length)
+        return true;
+    if (cb.fixed) {
+        cb.overflowed = true;
+        return false;
+    }
+    let newLen = cb.words.length;
+    while (cb.head + need > newLen)
+        newLen = newLen === 0 ? need : newLen * 2;
+    const next = new Uint32Array(newLen);
+    next.set(cb.words.subarray(0, cb.head));
+    cb.words = next;
+    return true;
+}
+//# sourceMappingURL=buffer.js.map

package/dist/commands/buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.js","sourceRoot":"","sources":["../../src/commands/buffer.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,mGAAmG;AACnG,EAAE;AACF,2EAA2E;AAC3E,sGAAsG;AACtG,iGAAiG;AACjG,qGAAqG;AACrG,2EAA2E;AAC3E,qGAAqG;AACrG,qEAAqE;AAuCrE,MAAM,iBAAiB,GAAsB,EAAE,OAAO,EAAE,EAAE,EAAE,CAAA;AAE5D,MAAM,UAAU,iBAAiB,CAAC,WAAmB,EAAE,YAAoB,EAAE,MAAe;IAC1F,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,EAAE,CAAC,GAAG,CAAC,CAAA;IAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,CAAA;IAC9E,OAAO;QACL,WAAW;QACX,KAAK,EAAE,IAAI,WAAW,CAAC,OAAO,CAAC;QAC/B,IAAI,EAAE,CAAC;QACP,WAAW,EAAE,CAAC;QACd,WAAW,EAAE,iBAAiB;QAC9B,iBAAiB,EAAE,CAAC;QACpB,kBAAkB,EAAE,CAAC;QACrB,KAAK,EAAE,MAAM;QACb,UAAU,EAAE,KAAK;QACjB,cAAc,EAAE,KAAK;KACtB,CAAA;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,WAAW,CAAC,EAAiB;IAC3C,EAAE,CAAC,IAAI,GAAG,CAAC,CAAA;IACX,EAAE,CAAC,WAAW,GAAG,CAAC,CAAA;IAClB,EAAE,CAAC,iBAAiB,GAAG,CAAC,CAAA;IACxB,EAAE,CAAC,kBAAkB,GAAG,CAAC,CAAA;IACzB,EAAE,CAAC,UAAU,GAAG,KAAK,CAAA;IACrB,EAAE,CAAC,cAAc,GAAG,KAAK,CAAA;AAC3B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,EAAiB,EAAE,IAAY;IACzD,IAAI,EAAE,CAAC,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IAClD,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,EAAE,CAAC,UAAU,GAAG,IAAI,CAAA;QACpB,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,MAAM,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAA;IAC5B,OAAO,EAAE,CAAC,IAAI,GAAG,IAAI,GAAG,MAAM;QAAE,MAAM,GAAG,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAA;IACzE,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,CAAA;IACpC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAA;IACvC,EAAE,CAAC,KAAK,GAAG,IAAI,CAAA;IACf,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/commands/encode.d.ts

@@ -0,0 +1,30 @@
+import type { CommandBuffer } from './buffer.js';
+import type { ComponentFieldCodec } from './fields.js';
+import type { ComponentDef, ComponentId, RelationId, Schema } from '@ecsia/schema';
+import type { EntityHandle } from '@ecsia/core';
+/** Per-component encode metadata the worker resolves from its replicated registry. */
+export interface ComponentEncodeInfo {
+    readonly id: ComponentId;
+    readonly codec: ComponentFieldCodec;
+}
+export interface CommandEncoder {
+    /** Reserve-and-return a usable handle NOW; emits OP_CREATE. Mid-wave safe. */
+    create(): EntityHandle;
+    destroy(h: EntityHandle): void;
+    add(h: EntityHandle, def: ComponentDef<Schema>, init?: Record<string, unknown>): void;
+    remove(h: EntityHandle, def: ComponentDef<Schema>): void;
+    setPayload(h: EntityHandle, def: ComponentDef<Schema>, values: Record<string, unknown>): void;
+    setRelation(subject: EntityHandle, relationId: RelationId, target: EntityHandle, payload?: Record<string, unknown>): void;
+    unsetRelation(subject: EntityHandle, relationId: RelationId, target: EntityHandle): void;
+}
+export interface EncoderEnv {
+    readonly cb: CommandBuffer;
+    /** Resolve a registered ComponentDef → its dense id + field codec. */
+    infoOf(def: ComponentDef<Schema>): ComponentEncodeInfo;
+    /** Field codec for a relation payload schema (or undefined for a tag relation). */
+    relationCodec(relationId: RelationId): ComponentFieldCodec | undefined;
+    /** Dev diagnostic sink (e.g. reservation exhaustion). */
+    warn(message: string): void;
+}
+export declare function makeEncoder(env: EncoderEnv): CommandEncoder;
+//# sourceMappingURL=encode.d.ts.map

package/dist/commands/encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../src/commands/encode.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAElF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,MAAM,IAAI,YAAY,CAAA;IACtB,OAAO,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IAC9B,GAAG,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACrF,MAAM,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,IAAI,CAAA;IACxD,UAAU,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC7F,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACzH,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;CACzF;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,sEAAsE;IACtE,MAAM,CAAC,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,mBAAmB,CAAA;IACtD,mFAAmF;IACnF,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,mBAAmB,GAAG,SAAS,CAAA;IACtE,yDAAyD;IACzD,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,cAAc,CAoG3D"}

package/dist/commands/encode.js

@@ -0,0 +1,108 @@
+// The worker-side encode API: the methods a system calls mid-wave. NONE
+// mutates shared structure — each appends one record to the owning worker's buffer (and, for create,
+// consumes a reserved handle). The ergonomic surface (entity.add, world.spawn inside a worker) routes
+// here via the worker's structuralOp seam (workers/worker-context.ts).
+import { Op } from './op.js';
+import { ensureWords } from './buffer.js';
+import { NO_ENTITY } from '@ecsia/core';
+export function makeEncoder(env) {
+    const { cb } = env;
+    /** Emit the overflow diagnostic ONCE per wave (the first capped record); subsequent caps are silent. */
+    function onOverflow() {
+        if (!cb.overflowed || cb.overflowWarned)
+            return;
+        cb.overflowWarned = true;
+        env.warn('command-buffer: fixed (SAB) buffer full; record dropped (raise commandWords)');
+    }
+    function create() {
+        if (cb.reservationCursor >= cb.reservation.handles.length) {
+            env.warn('command-buffer: reservation exhausted; raise maxSpawnsPerWave (spawn capped)');
+            return NO_ENTITY;
+        }
+        // Check capacity BEFORE consuming the reservation handle: an overflow must not burn a reserved id
+        // (and must emit no OP_CREATE) so the handle is reclaimed by returnUnused, not leaked.
+        if (!ensureWords(cb, 2)) {
+            onOverflow();
+            return NO_ENTITY;
+        }
+        const h = cb.reservation.handles[cb.reservationCursor];
+        cb.reservationCursor += 1;
+        const w = cb.head;
+        cb.words[w] = Op.CREATE;
+        cb.words[w + 1] = h;
+        cb.head += 2;
+        cb.recordCount += 1;
+        return h;
+    }
+    function destroy(h) {
+        if (!ensureWords(cb, 2))
+            return onOverflow();
+        const w = cb.head;
+        cb.words[w] = Op.DESTROY;
+        cb.words[w + 1] = h;
+        cb.head += 2;
+        cb.recordCount += 1;
+    }
+    function fieldRecord(op, h, def, init) {
+        const info = env.infoOf(def);
+        const f = info.codec.totalWords;
+        if (!ensureWords(cb, 4 + f))
+            return onOverflow();
+        const w = cb.head;
+        cb.words[w] = op;
+        cb.words[w + 1] = h;
+        cb.words[w + 2] = info.id;
+        cb.words[w + 3] = f;
+        info.codec.encode(init, cb.words, w + 4);
+        cb.head += 4 + f;
+        cb.recordCount += 1;
+    }
+    function remove(h, def) {
+        const info = env.infoOf(def);
+        if (!ensureWords(cb, 3))
+            return onOverflow();
+        const w = cb.head;
+        cb.words[w] = Op.REMOVE;
+        cb.words[w + 1] = h;
+        cb.words[w + 2] = info.id;
+        cb.head += 3;
+        cb.recordCount += 1;
+    }
+    function setRelation(subject, relationId, target, payload) {
+        const codec = env.relationCodec(relationId);
+        const p = codec?.totalWords ?? 0;
+        if (!ensureWords(cb, 5 + p))
+            return onOverflow();
+        const w = cb.head;
+        cb.words[w] = Op.ADD_PAIR;
+        cb.words[w + 1] = subject;
+        cb.words[w + 2] = relationId;
+        cb.words[w + 3] = target;
+        cb.words[w + 4] = p;
+        if (codec !== undefined && p > 0)
+            codec.encode(payload, cb.words, w + 5);
+        cb.head += 5 + p;
+        cb.recordCount += 1;
+    }
+    function unsetRelation(subject, relationId, target) {
+        if (!ensureWords(cb, 4))
+            return onOverflow();
+        const w = cb.head;
+        cb.words[w] = Op.REMOVE_PAIR;
+        cb.words[w + 1] = subject;
+        cb.words[w + 2] = relationId;
+        cb.words[w + 3] = target;
+        cb.head += 4;
+        cb.recordCount += 1;
+    }
+    return {
+        create,
+        destroy,
+        add: (h, def, init) => fieldRecord(Op.ADD, h, def, init),
+        remove,
+        setPayload: (h, def, values) => fieldRecord(Op.SET_PAYLOAD, h, def, values),
+        setRelation,
+        unsetRelation,
+    };
+}
+//# sourceMappingURL=encode.js.map

package/dist/commands/encode.js.map

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

package/dist/commands/fields.d.ts

@@ -0,0 +1,22 @@
+import type { ComponentDef, Schema } from '@ecsia/schema';
+interface FieldCodec {
+    readonly name: string;
+    /** Words this field occupies (1, or 2 for f64; `len`/`2*len` for vec). */
+    readonly words: number;
+    /** Encode the JS value into `out[at..at+words)`. */
+    readonly encode: (value: unknown, out: Uint32Array, at: number) => void;
+    /** Decode `words[at..at+words)` back to the JS value the accessor write-view expects. */
+    readonly decode: (words: Uint32Array, at: number) => unknown;
+}
+export interface ComponentFieldCodec {
+    /** Total payload words for the component (sum of field words; 0 for a tag). */
+    readonly totalWords: number;
+    readonly fields: readonly FieldCodec[];
+    /** Encode an `init` object → field words written at `out[at..]`; returns words written. */
+    encode(init: Record<string, unknown> | undefined, out: Uint32Array, at: number): number;
+    /** Decode `words[at..]` → a `{ field: value }` object for the accessor write-view. */
+    decode(words: Uint32Array, at: number): Record<string, unknown>;
+}
+export declare function buildFieldCodec(def: ComponentDef<Schema>): ComponentFieldCodec;
+export {};
+//# sourceMappingURL=fields.d.ts.map