@oasys/oecs 0.3.1 → 0.5.0

package/dist/core/store/command_dispatch.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Command dispatch — the generic drain surface a consumer registers against
+ * (#624, game-agnostic ECS / epic #616).
+ *
+ * The command ring (`command_ring.ts`) carries opaque `(opCode, payload)`
+ * slots; the engine never interprets a code. This module is the thin,
+ * game-free glue that lets a consumer bind a payload codec + typed handler to
+ * each opcode and drain the ring in one call. The opcode enum and the codecs
+ * themselves stay consumer-owned — for our game they live in
+ * `@internal/sim`'s `command_payloads.ts` (`COMMAND_OP`, `SpawnUnitFields`,
+ * `encode/decode_spawn_unit_payload`); the engine knows none of those names.
+ *
+ * Usage:
+ *
+ *   const dispatcher = new CommandDispatcher()
+ *     .on(COMMAND_OP.spawn_unit, spawn_unit_codec, (fields) => spawn(fields));
+ *   dispatcher.drain(view, ringOff); // runs after wasm.tick() returns
+ *
+ * Unregistered opcodes are skipped (the same forward-compatible stance as the
+ * raw `drainCommandRing` handler that ignores codes it doesn't know).
+ */
+/** Decode (and, symmetrically, encode) the 15-byte payload region of a
+ * command slot into a typed value. A consumer supplies one per opcode it
+ * cares about; the engine only ever calls `decode` during a drain, but the
+ * `encode` half keeps the codec a single round-trippable unit (and is what
+ * test/host producers use to push). */
+export interface PayloadCodec<T> {
+    /** Encode `value` into a fresh `COMMAND_RING_SLOT_BYTES - 1` (15) byte
+     * payload, ready for `pushCommand(view, off, op, payload)`. */
+    encode(value: T): Uint8Array;
+    /** Decode a 15-byte payload back into the typed value. */
+    decode(payload: Uint8Array): T;
+}
+/**
+ * Registry mapping command opcodes to a payload codec + handler. Generic over
+ * the consumer's opcodes — the engine ships the mechanism; the game supplies
+ * the codes and codecs.
+ */
+export declare class CommandDispatcher {
+    private readonly bindings;
+    /** Register `handler` for `opCode`, decoding each slot with `codec`.
+     * Re-registering an opcode replaces its binding. `opCode` must be a u8 in
+     * `[1, 255]` — `0` is the reserved empty-slot marker and can never carry a
+     * command. Returns `this` for chaining. */
+    on<T>(opCode: number, codec: PayloadCodec<T>, handler: (value: T) => void): this;
+    /** Drain every pending command, decoding + dispatching each to its
+     * registered handler. Commands with no registered opcode are skipped.
+     * Returns the number of slots drained (including skipped ones — the ring is
+     * advanced regardless, matching `drainCommandRing`). */
+    drain(view: DataView, ringOff: number): number;
+}
+//# sourceMappingURL=command_dispatch.d.ts.map

package/dist/core/store/command_dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command_dispatch.d.ts","sourceRoot":"","sources":["../../../src/core/store/command_dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;;uCAIuC;AACvC,MAAM,WAAW,YAAY,CAAC,CAAC;IAC9B;mEAC+D;IAC/D,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC;IAC7B,0DAA0D;IAC1D,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,CAAC,CAAC;CAC/B;AAWD;;;;GAIG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAE7D;;;+CAG2C;IAC3C,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,IAAI;IAgBhF;;;4DAGwD;IACxD,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;CAO9C"}

package/dist/core/store/command_ring.d.cts

@@ -0,0 +1,107 @@
+/**
+ * Command ring — WASM-side producer / TS-side consumer SPSC ring buffer
+ * for structural-change intents emitted during `sim.tick()`. Plan §7.5
+ * (`docs/ideas/buffer-wasm-sim-plan-2026-05-14T1600.md`).
+ *
+ * Layout:
+ *
+ *   [ write_head:   u32 ]   slot 0..N-1, monotonic (NOT slot-modulo)
+ *   [ read_head:    u32 ]   slot 0..N-1, monotonic
+ *   [ capacity:     u32 ]   slot count, power-of-two
+ *   [ overflow:     u32 ]   0 = OK; 1 = WASM exhausted the ring this tick
+ *   [ slot 0:       16 B ]  opCode: u8, payload: [15]u8
+ *   [ slot 1:       16 B ]  ...
+ *   ...
+ *
+ * SPSC contract (Phase 4 scope):
+ *   - Producer: WASM `sim.tick()`. Pushes 0..N commands during one tick;
+ *     bumps `write_head` after each.
+ *   - Consumer: TS host, immediately after `wasm.tick()` returns. Drains
+ *     0..N pending commands; bumps `read_head` after each.
+ *   - The two never run concurrently in Phase 4 (single host thread
+ *     orchestrates both). Phase 5's worker offload promotes the head
+ *     bumps to `Atomics.store`; that's an additive change without
+ *     altering the layout.
+ *
+ * Overflow:
+ *   - If WASM would write a slot when (`write_head - read_head == capacity`),
+ *     it sets `overflow = 1` and drops the command. TS treats overflow as
+ *     a hard error in dev builds; production logs and continues (a command
+ *     might be lost rather than crash the host).
+ *
+ * Slot format (plan §7.5):
+ *   byte 0:       opCode (u8). 0 is reserved as the empty-slot marker
+ *                 (`COMMAND_OP_EMPTY`); all other codes are consumer-defined.
+ *                 The engine never interprets a code — it drains
+ *                 `(opCode, payload)` and hands them to the attached
+ *                 consumer, which owns the opcode enum + payload codecs (the
+ *                 game's live in `@internal/sim`'s `command_payloads.ts`).
+ *   bytes 1..15:  payload, op-specific. Multi-byte fields may be
+ *                 unaligned within the payload; readers must use byte-
+ *                 oriented helpers (DataView in TS, `mem.readInt` in Zig).
+ *
+ * The ring lives BEFORE the layout-descriptor region in the SAB (right
+ * after the 32-byte header) so its offset is stable across descriptor /
+ * column-region growth. The host writes `header.command_ring_off` to
+ * point at it during `createColumnStore`; absent ring is signalled by
+ * `command_ring_off === 0`.
+ */
+/** Total bytes for the ring header. */
+export declare const COMMAND_RING_HEADER_BYTES = 16;
+/** Fixed slot size — 1-byte opCode + 15-byte payload. */
+export declare const COMMAND_RING_SLOT_BYTES = 16;
+/** Default ring capacity in slots. 256 × 16 B = 4 KiB of ring data plus
+ * 16 B header. Sized for the worst-case burst (peak spawn intents per
+ * tick) × small safety margin. Tune up if a Phase 4 burst pushes past it
+ * in the bench harness. */
+export declare const COMMAND_RING_DEFAULT_CAPACITY_SLOTS = 256;
+/** Byte offsets within the ring header. Mirrored on the Zig side in
+ * `packages/sim/src/command_ring.zig` — keep in sync. */
+export declare const COMMAND_RING_HEADER_OFFSETS: {
+    readonly write_head: 0;
+    readonly read_head: 4;
+    readonly capacity_slots: 8;
+    readonly overflow_flag: 12;
+};
+/** Op-code `0` is reserved across the SAB layer as the empty-slot marker
+ * so a zero-initialised SAB doesn't appear to hold a valid command (mirror
+ * of `EVENT_OP_EMPTY`). All non-zero codes are opaque to the engine —
+ * the attached consumer owns the opcode enum + payload codecs (the game's
+ * `COMMAND_OP` + `SpawnUnitFields` live in `@internal/sim`). */
+export declare const COMMAND_OP_EMPTY = 0;
+/** Total bytes the ring occupies for `capacity_slots` slots. */
+export declare function commandRingBytes(capacitySlots: number): number;
+export declare class CommandRingError extends Error {
+    constructor(message: string);
+}
+/** Initialise the ring header at `ringOff` in the SAB. Zeroes
+ * `write_head`, `read_head`, and `overflow_flag`; sets `capacity_slots`.
+ * Slot bytes are left as-is (callers normally allocate the ring on a
+ * fresh, zero-initialised SAB). */
+export declare function initCommandRing(view: DataView, ringOff: number, capacitySlots: number): void;
+/** Read live ring-header field. */
+export declare function ringWriteHead(view: DataView, ringOff: number): number;
+export declare function ringReadHead(view: DataView, ringOff: number): number;
+export declare function ringCapacitySlots(view: DataView, ringOff: number): number;
+export declare function ringOverflow(view: DataView, ringOff: number): boolean;
+/** Pending command count = `(write_head - read_head) mod 2^32`. The
+ * `>>> 0` keeps the result a u32 in the wrap-around case (rings live for
+ * the host's lifetime; 2^32 commands at 50 Hz ≈ 2 years, but the
+ * arithmetic should be correct regardless). */
+export declare function pendingCommandCount(view: DataView, ringOff: number): number;
+/** Push a command into the ring from the TS side. Production producer is
+ * WASM (via `command_ring.zig`); this is for host-side tests and for
+ * symmetric tests across the two sides. Returns `false` on overflow and
+ * sets the overflow flag. Payload must be exactly 15 bytes. */
+export declare function pushCommand(view: DataView, ringOff: number, opCode: number, payload: Uint8Array): boolean;
+/** Read one command from the ring. Returns opCode (0 = empty/no
+ * command) and fills `outPayload` (15 bytes) with the slot's payload.
+ * When 0 is returned, `outPayload` is untouched. */
+export declare function popCommand(view: DataView, ringOff: number, outPayload: Uint8Array): number;
+/** Visit every pending command and bump `read_head` past them. Yields
+ * `{ opCode, payload }` per slot where `payload` is a freshly-copied
+ * 15-byte Uint8Array (so the handler can hold it past the next pop
+ * without aliasing the ring). Stops when the ring is empty. Used by the
+ * TS host drain that runs right after `wasm.tick()` returns. */
+export declare function drainCommandRing(view: DataView, ringOff: number, handler: (opCode: number, payload: Uint8Array) => void): number;
+//# sourceMappingURL=command_ring.d.ts.map

package/dist/core/store/command_ring.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Command ring — WASM-side producer / TS-side consumer SPSC ring buffer
+ * for structural-change intents emitted during `sim.tick()`. Plan §7.5
+ * (`docs/ideas/buffer-wasm-sim-plan-2026-05-14T1600.md`).
+ *
+ * Layout:
+ *
+ *   [ write_head:   u32 ]   slot 0..N-1, monotonic (NOT slot-modulo)
+ *   [ read_head:    u32 ]   slot 0..N-1, monotonic
+ *   [ capacity:     u32 ]   slot count, power-of-two
+ *   [ overflow:     u32 ]   0 = OK; 1 = WASM exhausted the ring this tick
+ *   [ slot 0:       16 B ]  opCode: u8, payload: [15]u8
+ *   [ slot 1:       16 B ]  ...
+ *   ...
+ *
+ * SPSC contract (Phase 4 scope):
+ *   - Producer: WASM `sim.tick()`. Pushes 0..N commands during one tick;
+ *     bumps `write_head` after each.
+ *   - Consumer: TS host, immediately after `wasm.tick()` returns. Drains
+ *     0..N pending commands; bumps `read_head` after each.
+ *   - The two never run concurrently in Phase 4 (single host thread
+ *     orchestrates both). Phase 5's worker offload promotes the head
+ *     bumps to `Atomics.store`; that's an additive change without
+ *     altering the layout.
+ *
+ * Overflow:
+ *   - If WASM would write a slot when (`write_head - read_head == capacity`),
+ *     it sets `overflow = 1` and drops the command. TS treats overflow as
+ *     a hard error in dev builds; production logs and continues (a command
+ *     might be lost rather than crash the host).
+ *
+ * Slot format (plan §7.5):
+ *   byte 0:       opCode (u8). 0 is reserved as the empty-slot marker
+ *                 (`COMMAND_OP_EMPTY`); all other codes are consumer-defined.
+ *                 The engine never interprets a code — it drains
+ *                 `(opCode, payload)` and hands them to the attached
+ *                 consumer, which owns the opcode enum + payload codecs (the
+ *                 game's live in `@internal/sim`'s `command_payloads.ts`).
+ *   bytes 1..15:  payload, op-specific. Multi-byte fields may be
+ *                 unaligned within the payload; readers must use byte-
+ *                 oriented helpers (DataView in TS, `mem.readInt` in Zig).
+ *
+ * The ring lives BEFORE the layout-descriptor region in the SAB (right
+ * after the 32-byte header) so its offset is stable across descriptor /
+ * column-region growth. The host writes `header.command_ring_off` to
+ * point at it during `createColumnStore`; absent ring is signalled by
+ * `command_ring_off === 0`.
+ */
+/** Total bytes for the ring header. */
+export declare const COMMAND_RING_HEADER_BYTES = 16;
+/** Fixed slot size — 1-byte opCode + 15-byte payload. */
+export declare const COMMAND_RING_SLOT_BYTES = 16;
+/** Default ring capacity in slots. 256 × 16 B = 4 KiB of ring data plus
+ * 16 B header. Sized for the worst-case burst (peak spawn intents per
+ * tick) × small safety margin. Tune up if a Phase 4 burst pushes past it
+ * in the bench harness. */
+export declare const COMMAND_RING_DEFAULT_CAPACITY_SLOTS = 256;
+/** Byte offsets within the ring header. Mirrored on the Zig side in
+ * `packages/sim/src/command_ring.zig` — keep in sync. */
+export declare const COMMAND_RING_HEADER_OFFSETS: {
+    readonly write_head: 0;
+    readonly read_head: 4;
+    readonly capacity_slots: 8;
+    readonly overflow_flag: 12;
+};
+/** Op-code `0` is reserved across the SAB layer as the empty-slot marker
+ * so a zero-initialised SAB doesn't appear to hold a valid command (mirror
+ * of `EVENT_OP_EMPTY`). All non-zero codes are opaque to the engine —
+ * the attached consumer owns the opcode enum + payload codecs (the game's
+ * `COMMAND_OP` + `SpawnUnitFields` live in `@internal/sim`). */
+export declare const COMMAND_OP_EMPTY = 0;
+/** Total bytes the ring occupies for `capacity_slots` slots. */
+export declare function commandRingBytes(capacitySlots: number): number;
+export declare class CommandRingError extends Error {
+    constructor(message: string);
+}
+/** Initialise the ring header at `ringOff` in the SAB. Zeroes
+ * `write_head`, `read_head`, and `overflow_flag`; sets `capacity_slots`.
+ * Slot bytes are left as-is (callers normally allocate the ring on a
+ * fresh, zero-initialised SAB). */
+export declare function initCommandRing(view: DataView, ringOff: number, capacitySlots: number): void;
+/** Read live ring-header field. */
+export declare function ringWriteHead(view: DataView, ringOff: number): number;
+export declare function ringReadHead(view: DataView, ringOff: number): number;
+export declare function ringCapacitySlots(view: DataView, ringOff: number): number;
+export declare function ringOverflow(view: DataView, ringOff: number): boolean;
+/** Pending command count = `(write_head - read_head) mod 2^32`. The
+ * `>>> 0` keeps the result a u32 in the wrap-around case (rings live for
+ * the host's lifetime; 2^32 commands at 50 Hz ≈ 2 years, but the
+ * arithmetic should be correct regardless). */
+export declare function pendingCommandCount(view: DataView, ringOff: number): number;
+/** Push a command into the ring from the TS side. Production producer is
+ * WASM (via `command_ring.zig`); this is for host-side tests and for
+ * symmetric tests across the two sides. Returns `false` on overflow and
+ * sets the overflow flag. Payload must be exactly 15 bytes. */
+export declare function pushCommand(view: DataView, ringOff: number, opCode: number, payload: Uint8Array): boolean;
+/** Read one command from the ring. Returns opCode (0 = empty/no
+ * command) and fills `outPayload` (15 bytes) with the slot's payload.
+ * When 0 is returned, `outPayload` is untouched. */
+export declare function popCommand(view: DataView, ringOff: number, outPayload: Uint8Array): number;
+/** Visit every pending command and bump `read_head` past them. Yields
+ * `{ opCode, payload }` per slot where `payload` is a freshly-copied
+ * 15-byte Uint8Array (so the handler can hold it past the next pop
+ * without aliasing the ring). Stops when the ring is empty. Used by the
+ * TS host drain that runs right after `wasm.tick()` returns. */
+export declare function drainCommandRing(view: DataView, ringOff: number, handler: (opCode: number, payload: Uint8Array) => void): number;
+//# sourceMappingURL=command_ring.d.ts.map

package/dist/core/store/command_ring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command_ring.d.ts","sourceRoot":"","sources":["../../../src/core/store/command_ring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,uCAAuC;AACvC,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,yDAAyD;AACzD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;;;2BAG2B;AAC3B,eAAO,MAAM,mCAAmC,MAAM,CAAC;AAEvD;yDACyD;AACzD,eAAO,MAAM,2BAA2B;;;;;CAK9B,CAAC;AAEX;;;;gEAIgE;AAChE,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9D;AASD,qBAAa,gBAAiB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI3B;AAED;;;mCAGmC;AACnC,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAU5F;AAED,mCAAmC;AACnC,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAErE;AACD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpE;AACD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE;AACD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAErE;AAED;;;+CAG+C;AAC/C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;+DAG+D;AAC/D,wBAAgB,WAAW,CAC1B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,UAAU,GACjB,OAAO,CAmCT;AAED;;oDAEoD;AACpD,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAiB1F;AAED;;;;gEAIgE;AAChE,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,KAAK,IAAI,GACpD,MAAM,CAWR"}

package/dist/core/store/descriptor.d.cts

@@ -0,0 +1,80 @@
+import { COLUMN_DESCRIPTOR_BYTES, COLUMN_DESCRIPTOR_OFFSETS, ARCHETYPE_DESCRIPTOR_HEADER_BYTES, ARCHETYPE_DESCRIPTOR_OFFSETS, COMPONENT_MASK_WORDS } from './vendored_abi/abi.cjs';
+export { COLUMN_DESCRIPTOR_BYTES, COLUMN_DESCRIPTOR_OFFSETS, ARCHETYPE_DESCRIPTOR_HEADER_BYTES, ARCHETYPE_DESCRIPTOR_OFFSETS, COMPONENT_MASK_WORDS };
+/** type_tag values for `ColumnDescriptor.type_tag`. The order matches the
+ * TypedArrayTag union in `packages/std/type_primitives` so a tag's element
+ * width is `TYPE_TAG_STRIDE[tag]`. */
+export declare const TYPE_TAG: {
+    readonly u8: 0;
+    readonly i8: 1;
+    readonly u16: 2;
+    readonly i16: 3;
+    readonly u32: 4;
+    readonly i32: 5;
+    readonly f32: 6;
+    readonly f64: 7;
+};
+export type TypeTagValue = (typeof TYPE_TAG)[keyof typeof TYPE_TAG];
+/** Element width in bytes for each `TYPE_TAG`. Indexed by tag value so a
+ * `stride = TYPE_TAG_STRIDE[tag]` lookup is O(1) array access. */
+export declare const TYPE_TAG_STRIDE: Readonly<Record<TypeTagValue, number>>;
+/** String-tag → numeric-tag bridge. `TypedArrayTag` ("u8", "f32", …) is the
+ * vocabulary the TS-side component registry speaks; `TypeTagValue` is the
+ * numeric enum the SAB descriptors carry on the wire. Bridging happens at
+ * the ECS↔SAB seam — Archetype layouts come in as strings, ColumnSpecs go
+ * out as integers. */
+export declare const TYPED_ARRAY_TAG_TO_TYPE_TAG: {
+    readonly u8: 0;
+    readonly i8: 1;
+    readonly u16: 2;
+    readonly i16: 3;
+    readonly u32: 4;
+    readonly i32: 5;
+    readonly f32: 6;
+    readonly f64: 7;
+};
+export interface ColumnDescriptor {
+    readonly componentId: number;
+    readonly fieldId: number;
+    readonly typeTag: TypeTagValue;
+    /** Byte offset of the column's first row, measured from SAB byte 0. */
+    readonly byteOff: number;
+    /** Element width in bytes; should always equal `TYPE_TAG_STRIDE[type_tag]`. */
+    readonly stride: number;
+}
+export declare function writeColumnDescriptor(view: DataView, off: number, c: ColumnDescriptor): void;
+export declare function readColumnDescriptor(view: DataView, off: number): ColumnDescriptor;
+/** Number of distinct components the cross-language ECS supports:
+ * `COMPONENT_MASK_WORDS × 32` bits in the SAB archetype descriptor mask. The
+ * Zig side matches archetypes purely on this mask, so a component whose ID is
+ * ≥ this limit would be invisible there while the heap-side `BitSet` stayed
+ * correct — silently conflating archetypes that differ only in such a
+ * component. `Store.registerComponent` enforces this as a hard registration
+ * ceiling so the overflow fails loudly instead (#381). The mask is sized to
+ * the `BitSet`'s `INITIAL_WORD_COUNT`, so a registry within the limit never
+ * grows a component mask past its initial words. */
+export declare const STORE_DESCRIPTOR_COMPONENT_LIMIT: number;
+export interface ArchetypeDescriptor {
+    readonly archetypeId: number;
+    /** Component bitmask, `COMPONENT_MASK_WORDS` little-endian u32 words. Word
+     * `w` holds component IDs in `[w*32, w*32+32)`. */
+    readonly componentMask: readonly number[];
+    readonly rowCount: number;
+    readonly rowCapacity: number;
+    /** Enabled-row count `≤ row_count` (#577 / #599). Per-row entity-scan loops in
+     * the WASM sim bound on this so disabled entities (swapped to the tail
+     * `[enabled_count, row_count)`) are not simulated; row-indexed cross-entity
+     * reads still use `row_count`. */
+    readonly enabledCount: number;
+    readonly columns: readonly ColumnDescriptor[];
+}
+/** Total bytes a descriptor will occupy, given its column count. Useful for
+ * planning the layout descriptor region size up front. */
+export declare function archetypeDescriptorBytes(columnCount: number): number;
+export declare function writeArchetypeDescriptor(view: DataView, off: number, d: ArchetypeDescriptor): number;
+export declare function readArchetypeDescriptor(view: DataView, off: number): ArchetypeDescriptor;
+export declare function writeLayoutDescriptorRegion(view: DataView, regionOff: number, descriptors: readonly ArchetypeDescriptor[]): number;
+export declare function readLayoutDescriptorRegion(view: DataView, regionOff: number, archetypeCount: number): readonly ArchetypeDescriptor[];
+/** Total bytes needed for a layout descriptor region holding these archetypes.
+ * Use to size the SAB region between header end and the first column. */
+export declare function layoutDescriptorRegionBytes(descriptors: readonly ArchetypeDescriptor[]): number;
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/core/store/descriptor.d.ts

@@ -0,0 +1,80 @@
+import { COLUMN_DESCRIPTOR_BYTES, COLUMN_DESCRIPTOR_OFFSETS, ARCHETYPE_DESCRIPTOR_HEADER_BYTES, ARCHETYPE_DESCRIPTOR_OFFSETS, COMPONENT_MASK_WORDS } from './vendored_abi/abi.js';
+export { COLUMN_DESCRIPTOR_BYTES, COLUMN_DESCRIPTOR_OFFSETS, ARCHETYPE_DESCRIPTOR_HEADER_BYTES, ARCHETYPE_DESCRIPTOR_OFFSETS, COMPONENT_MASK_WORDS };
+/** type_tag values for `ColumnDescriptor.type_tag`. The order matches the
+ * TypedArrayTag union in `packages/std/type_primitives` so a tag's element
+ * width is `TYPE_TAG_STRIDE[tag]`. */
+export declare const TYPE_TAG: {
+    readonly u8: 0;
+    readonly i8: 1;
+    readonly u16: 2;
+    readonly i16: 3;
+    readonly u32: 4;
+    readonly i32: 5;
+    readonly f32: 6;
+    readonly f64: 7;
+};
+export type TypeTagValue = (typeof TYPE_TAG)[keyof typeof TYPE_TAG];
+/** Element width in bytes for each `TYPE_TAG`. Indexed by tag value so a
+ * `stride = TYPE_TAG_STRIDE[tag]` lookup is O(1) array access. */
+export declare const TYPE_TAG_STRIDE: Readonly<Record<TypeTagValue, number>>;
+/** String-tag → numeric-tag bridge. `TypedArrayTag` ("u8", "f32", …) is the
+ * vocabulary the TS-side component registry speaks; `TypeTagValue` is the
+ * numeric enum the SAB descriptors carry on the wire. Bridging happens at
+ * the ECS↔SAB seam — Archetype layouts come in as strings, ColumnSpecs go
+ * out as integers. */
+export declare const TYPED_ARRAY_TAG_TO_TYPE_TAG: {
+    readonly u8: 0;
+    readonly i8: 1;
+    readonly u16: 2;
+    readonly i16: 3;
+    readonly u32: 4;
+    readonly i32: 5;
+    readonly f32: 6;
+    readonly f64: 7;
+};
+export interface ColumnDescriptor {
+    readonly componentId: number;
+    readonly fieldId: number;
+    readonly typeTag: TypeTagValue;
+    /** Byte offset of the column's first row, measured from SAB byte 0. */
+    readonly byteOff: number;
+    /** Element width in bytes; should always equal `TYPE_TAG_STRIDE[type_tag]`. */
+    readonly stride: number;
+}
+export declare function writeColumnDescriptor(view: DataView, off: number, c: ColumnDescriptor): void;
+export declare function readColumnDescriptor(view: DataView, off: number): ColumnDescriptor;
+/** Number of distinct components the cross-language ECS supports:
+ * `COMPONENT_MASK_WORDS × 32` bits in the SAB archetype descriptor mask. The
+ * Zig side matches archetypes purely on this mask, so a component whose ID is
+ * ≥ this limit would be invisible there while the heap-side `BitSet` stayed
+ * correct — silently conflating archetypes that differ only in such a
+ * component. `Store.registerComponent` enforces this as a hard registration
+ * ceiling so the overflow fails loudly instead (#381). The mask is sized to
+ * the `BitSet`'s `INITIAL_WORD_COUNT`, so a registry within the limit never
+ * grows a component mask past its initial words. */
+export declare const STORE_DESCRIPTOR_COMPONENT_LIMIT: number;
+export interface ArchetypeDescriptor {
+    readonly archetypeId: number;
+    /** Component bitmask, `COMPONENT_MASK_WORDS` little-endian u32 words. Word
+     * `w` holds component IDs in `[w*32, w*32+32)`. */
+    readonly componentMask: readonly number[];
+    readonly rowCount: number;
+    readonly rowCapacity: number;
+    /** Enabled-row count `≤ row_count` (#577 / #599). Per-row entity-scan loops in
+     * the WASM sim bound on this so disabled entities (swapped to the tail
+     * `[enabled_count, row_count)`) are not simulated; row-indexed cross-entity
+     * reads still use `row_count`. */
+    readonly enabledCount: number;
+    readonly columns: readonly ColumnDescriptor[];
+}
+/** Total bytes a descriptor will occupy, given its column count. Useful for
+ * planning the layout descriptor region size up front. */
+export declare function archetypeDescriptorBytes(columnCount: number): number;
+export declare function writeArchetypeDescriptor(view: DataView, off: number, d: ArchetypeDescriptor): number;
+export declare function readArchetypeDescriptor(view: DataView, off: number): ArchetypeDescriptor;
+export declare function writeLayoutDescriptorRegion(view: DataView, regionOff: number, descriptors: readonly ArchetypeDescriptor[]): number;
+export declare function readLayoutDescriptorRegion(view: DataView, regionOff: number, archetypeCount: number): readonly ArchetypeDescriptor[];
+/** Total bytes needed for a layout descriptor region holding these archetypes.
+ * Use to size the SAB region between header end and the first column. */
+export declare function layoutDescriptorRegionBytes(descriptors: readonly ArchetypeDescriptor[]): number;
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/core/store/descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../../src/core/store/descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAeH,OAAO,EACN,uBAAuB,EACvB,yBAAyB,EACzB,iCAAiC,EACjC,4BAA4B,EAC5B,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,uBAAuB,EACvB,yBAAyB,EACzB,iCAAiC,EACjC,4BAA4B,EAC5B,oBAAoB,EACpB,CAAC;AAEF;;sCAEsC;AACtC,eAAO,MAAM,QAAQ;;;;;;;;;CASX,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AAEpE;kEACkE;AAClE,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CASjE,CAAC;AAEH;;;;sBAIsB;AACtB,eAAO,MAAM,2BAA2B;;;;;;;;;CAS9B,CAAC;AAUX,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAS5F;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAQlF;AAeD;;;;;;;;oDAQoD;AACpD,eAAO,MAAM,gCAAgC,QAA4B,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;uDACmD;IACnD,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;sCAGkC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC9C;AAED;0DAC0D;AAC1D,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wBAAgB,wBAAwB,CACvC,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,MAAM,EACX,CAAC,EAAE,mBAAmB,GACpB,MAAM,CAoBR;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAuBxF;AAcD,wBAAgB,2BAA2B,CAC1C,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,SAAS,mBAAmB,EAAE,GACzC,MAAM,CAMR;AAED,wBAAgB,0BAA0B,CACzC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACpB,SAAS,mBAAmB,EAAE,CAShC;AAED;yEACyE;AACzE,wBAAgB,2BAA2B,CAC1C,WAAW,EAAE,SAAS,mBAAmB,EAAE,GACzC,MAAM,CAMR"}

package/dist/core/store/entity_index.d.cts

@@ -0,0 +1,108 @@
+/**
+ * Entity-index SAB region — `EntityID` → `(archetype_id, row, generation)`
+ * lookup table shared with the Zig sim. (#245 / Phase 4 PR 4B)
+ *
+ * Every hot fixed-update system that needs to resolve an `EntityID`
+ * held in a column (e.g. a component field that points at another
+ * entity → that entity's columns) has to do
+ * `entityId → archetype + row` translation. The plan forbids
+ * WASM-into-TS callbacks during `tick()` (§4 / §5.2), so the lookup
+ * tables must live in shared memory.
+ *
+ * Layout:
+ *
+ *   [ length:    u32 ]   high-water index (count of slots ever issued)
+ *   [ capacity:  u32 ]   backing-array length (slots × 1; not bytes)
+ *   [ _pad0:     u32 ]   alignment pad to 16 bytes
+ *   [ _pad1:     u32 ]   ───
+ *   [ generations[capacity]: i32 ]
+ *   [ archetypes[capacity]:  i32 ]
+ *   [ rows[capacity]:        i32 ]
+ *
+ * Sentinels:
+ *   - `generations[i] = 0` (INITIAL_GENERATION) for never-used slots.
+ *     Generation grows by 1 on every destroy; an `EntityID`'s generation
+ *     field matches `generations[index]` iff it's still alive.
+ *   - `archetypes[i] = -1` (UNASSIGNED) when the slot hasn't been placed
+ *     into an archetype, OR when the entity is destroyed.
+ *   - `rows[i]      = -1` (UNASSIGNED) on destroy / not-placed.
+ *
+ * Field width: i32 (signed) on the TS side so `-1` round-trips through
+ * `Int32Array` without unsigned coercion. Zig reads as i32 too — bit
+ * pattern is identical to u32 `0xFFFFFFFF` for the UNASSIGNED case, and
+ * for valid archetype_ids (bounded by `MAX_INDEX = 2^20`) the sign bit
+ * is never set, so signed/unsigned interpretation agrees.
+ *
+ * Region placement: between command ring and descriptor region so the
+ * offset is stable across descriptor / column-region growth (same
+ * property the command ring gets). Grow path (when entityHighWater
+ * exceeds `capacity`) uses `growColumnStore` — slow path, same as
+ * descriptor-region overflow.
+ *
+ * Reading from Zig: see `packages/sim/src/entity_index.zig` for the
+ * symmetric reader.
+ */
+/** Fixed bytes of the region header (length, capacity, two pad u32s for
+ * 16-byte alignment of the i32 arrays that follow). */
+export declare const ENTITY_INDEX_HEADER_BYTES = 16;
+/** Bytes per slot: three i32 columns. */
+export declare const ENTITY_INDEX_BYTES_PER_SLOT = 12;
+/** Byte offsets within the region header. Locked by the
+ * `entity_index.test.ts` golden bytes; any change here is a
+ * `SIM_ABI_VERSION` bump. */
+export declare const ENTITY_INDEX_HEADER_OFFSETS: {
+    readonly length: 0;
+    readonly capacity: 4;
+};
+/** Default initial slot count when the engine creates a Store. Matches
+ * `MAX_INDEX = (1 << 20) - 1 + 1 = 1_048_576` (the EntityID 20-bit index
+ * range, see `entity.ts`), so the region pre-sizes to the entire
+ * addressable entity space and `createEntity` can never run out under
+ * the default. 1M × 12 B ≈ 12 MiB SAB region — virtual memory only;
+ * physical pages allocate lazily via OS page-fault on first touch, so
+ * the typical 1000-entity workload pays for ~12 KiB physical even though the
+ * virtual reservation is 12 MiB.
+ *
+ * Tests / benches can pass a smaller `StoreOptions.entityIndexCapacity`
+ * to bench tighter reservations. A future PR will replace this with
+ * on-demand growth via `growColumnStore` so the default can drop. */
+export declare const ENTITY_INDEX_DEFAULT_CAPACITY: number;
+/** Total region bytes for `capacity` slots: header + 3 i32 columns. */
+export declare function entityIndexRegionBytes(capacity: number): number;
+/** Byte offset of the generations column within the region. */
+export declare function entityIndexGenerationsOff(regionOff: number): number;
+/** Byte offset of the archetype-id column. */
+export declare function entityIndexArchetypesOff(regionOff: number, capacity: number): number;
+/** Byte offset of the row column. */
+export declare function entityIndexRowsOff(regionOff: number, capacity: number): number;
+export declare class EntityIndexError extends Error {
+    constructor(message: string);
+}
+/** Initialise the region header at `regionOff`. Sets `length=0` and
+ * `capacity=<arg>`. The i32 arrays past the header are left untouched
+ * (callers normally allocate the region on a fresh, zero-initialised
+ * SAB; generation 0 is the INITIAL_GENERATION sentinel, archetype/row
+ * sentinels of 0 are caught by `length=0` so no read reaches them). */
+export declare function initEntityIndexRegion(view: DataView, regionOff: number, capacity: number): void;
+/** Read the region's current length (high-water index, ≤ capacity). */
+export declare function entityIndexLength(view: DataView, regionOff: number): number;
+/** Read the region's current capacity (backing-array length). */
+export declare function entityIndexCapacity(view: DataView, regionOff: number): number;
+/** Update the region's length (called from the engine's Store on every
+ * entity allocation that pushes `entityHighWater` past its previous
+ * value). */
+export declare function setEntityIndexLength(view: DataView, regionOff: number, length: number): void;
+/** Materialise the three Int32Array views over the region's column data
+ * for use by the engine's Store. The views live as long as the
+ * SharedArrayBuffer hasn't been reallocated — refresh on `view_stamp`
+ * bump (the engine's `_onBufferResized` callback).
+ *
+ * Three separate views (not a single struct-of-arrays object) because
+ * the engine's hot paths benefit from each being a direct typed-array
+ * read; V8 specialises `arr[i] = v` aggressively for typed arrays. */
+export declare function buildEntityIndexViews(buffer: ArrayBufferLike, regionOff: number, capacity: number): {
+    readonly generations: Int32Array;
+    readonly archetypes: Int32Array;
+    readonly rows: Int32Array;
+};
+//# sourceMappingURL=entity_index.d.ts.map