@oasys/oecs 0.5.4 → 0.6.0

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

@@ -1,61 +1,59 @@
 /**
- * Command ring — WASM-side producer / TS-side consumer SPSC ring buffer
+ * Command ring. A WASM-side producer and TS-side consumer SPSC ring buffer
  * for structural-change intents emitted during `sim.tick()`.
  *
  * Layout:
  *
- *   [ write_head:   u32 ]   slot 0..N-1, monotonic (NOT slot-modulo)
+ *   [ 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
+ *   [ 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 (single host thread):
- *   - Producer: WASM `sim.tick()`. Pushes 0..N commands during one tick;
+ *   - Producer: the WASM tick. It pushes 0..N commands during one tick and
  *     bumps `write_head` after each.
  *   - Consumer: TS host, immediately after `wasm.tick()` returns. Drains
- *     0..N pending commands; bumps `read_head` after each.
+ *     0..N pending commands. Bumps `read_head` after each.
  *   - The two never run concurrently (one host thread orchestrates
  *     both). A later worker offload promotes the head
- *     bumps to `Atomics.store`; that's an additive change without
+ *     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
+ *     a hard error in dev builds. Production logs and continues (a command
  *     might be lost rather than crash the host).
  *
  * Slot format:
  *   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`).
+ *                 (`COMMAND_OP_EMPTY`), and every other code is
+ *                 consumer-defined. The engine never interprets a code. It
+ *                 drains `(opCode, payload)` and hands them to the attached
+ *                 consumer, which owns the opcode enum and the payload codecs.
  *   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).
+ *                 unaligned within the payload. Readers must use byte-
+ *                 oriented helpers, such as a `DataView` in TS.
  *
- * 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
+ * The ring lives before the layout-descriptor region in the SAB (right
+ * after the `STORE_HEADER_BYTES` header) so its offset is stable across
+ * descriptor growth and 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. */
+/** 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 burst pushes past it
- * in the bench harness. */
+ * 16 B header. Sized for the worst-case burst of spawn intents in one tick,
+ * with a small safety margin. Tune it up when a burst pushes past it. */
 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. */
+/** Byte offsets within the ring header. A reader on the module side mirrors
+ * these offsets, so a change here is an ABI change. */
 export declare const COMMAND_RING_HEADER_OFFSETS: {
     readonly write_head: 0;
     readonly read_head: 4;
@@ -64,9 +62,8 @@ export declare const COMMAND_RING_HEADER_OFFSETS: {
 };
 /** 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`). */
+ * of `EVENT_OP_EMPTY`). Every non-zero code is opaque to the engine, and
+ * the attached consumer owns the opcode enum and the payload codecs. */
 export declare const COMMAND_OP_EMPTY = 0;
 /** Total bytes the ring occupies for `capacity_slots` slots. */
 export declare function commandRingBytes(capacitySlots: number): number;
@@ -74,26 +71,26 @@ 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`.
+ * `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;
+export declare function commandRingWriteHead(view: DataView, ringOff: number): number;
+export declare function commandRingReadHead(view: DataView, ringOff: number): number;
+export declare function commandRingCapacitySlots(view: DataView, ringOff: number): number;
+export declare function commandRingOverflow(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). */
+ * `>>> 0` keeps the result a u32 in the wrap-around case. A ring lives for
+ * the host's lifetime, so a long-lived host can reach the wrap, and the
+ * arithmetic has to stay correct there. */
 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
+/** Push a command into the ring from the TS side. The production producer is
+ * the WASM module, through its own ring writer. 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
+/** 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;

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

@@ -1,61 +1,59 @@
 /**
- * Command ring — WASM-side producer / TS-side consumer SPSC ring buffer
+ * Command ring. A WASM-side producer and TS-side consumer SPSC ring buffer
  * for structural-change intents emitted during `sim.tick()`.
  *
  * Layout:
  *
- *   [ write_head:   u32 ]   slot 0..N-1, monotonic (NOT slot-modulo)
+ *   [ 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
+ *   [ 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 (single host thread):
- *   - Producer: WASM `sim.tick()`. Pushes 0..N commands during one tick;
+ *   - Producer: the WASM tick. It pushes 0..N commands during one tick and
  *     bumps `write_head` after each.
  *   - Consumer: TS host, immediately after `wasm.tick()` returns. Drains
- *     0..N pending commands; bumps `read_head` after each.
+ *     0..N pending commands. Bumps `read_head` after each.
  *   - The two never run concurrently (one host thread orchestrates
  *     both). A later worker offload promotes the head
- *     bumps to `Atomics.store`; that's an additive change without
+ *     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
+ *     a hard error in dev builds. Production logs and continues (a command
  *     might be lost rather than crash the host).
  *
  * Slot format:
  *   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`).
+ *                 (`COMMAND_OP_EMPTY`), and every other code is
+ *                 consumer-defined. The engine never interprets a code. It
+ *                 drains `(opCode, payload)` and hands them to the attached
+ *                 consumer, which owns the opcode enum and the payload codecs.
  *   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).
+ *                 unaligned within the payload. Readers must use byte-
+ *                 oriented helpers, such as a `DataView` in TS.
  *
- * 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
+ * The ring lives before the layout-descriptor region in the SAB (right
+ * after the `STORE_HEADER_BYTES` header) so its offset is stable across
+ * descriptor growth and 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. */
+/** 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 burst pushes past it
- * in the bench harness. */
+ * 16 B header. Sized for the worst-case burst of spawn intents in one tick,
+ * with a small safety margin. Tune it up when a burst pushes past it. */
 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. */
+/** Byte offsets within the ring header. A reader on the module side mirrors
+ * these offsets, so a change here is an ABI change. */
 export declare const COMMAND_RING_HEADER_OFFSETS: {
     readonly write_head: 0;
     readonly read_head: 4;
@@ -64,9 +62,8 @@ export declare const COMMAND_RING_HEADER_OFFSETS: {
 };
 /** 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`). */
+ * of `EVENT_OP_EMPTY`). Every non-zero code is opaque to the engine, and
+ * the attached consumer owns the opcode enum and the payload codecs. */
 export declare const COMMAND_OP_EMPTY = 0;
 /** Total bytes the ring occupies for `capacity_slots` slots. */
 export declare function commandRingBytes(capacitySlots: number): number;
@@ -74,26 +71,26 @@ 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`.
+ * `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;
+export declare function commandRingWriteHead(view: DataView, ringOff: number): number;
+export declare function commandRingReadHead(view: DataView, ringOff: number): number;
+export declare function commandRingCapacitySlots(view: DataView, ringOff: number): number;
+export declare function commandRingOverflow(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). */
+ * `>>> 0` keeps the result a u32 in the wrap-around case. A ring lives for
+ * the host's lifetime, so a long-lived host can reach the wrap, and the
+ * arithmetic has to stay correct there. */
 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
+/** Push a command into the ring from the TS side. The production producer is
+ * the WASM module, through its own ring writer. 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
+/** 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;

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

@@ -1 +1 @@
-{"version":3,"file":"command_ring.d.ts","sourceRoot":"","sources":["../../../src/core/store/command_ring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;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"}
+{"version":3,"file":"command_ring.d.ts","sourceRoot":"","sources":["../../../src/core/store/command_ring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,uCAAuC;AACvC,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,wDAAwD;AACxD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;;yEAEyE;AACzE,eAAO,MAAM,mCAAmC,MAAM,CAAC;AAEvD;uDACuD;AACvD,eAAO,MAAM,2BAA2B;;;;;CAK9B,CAAC;AAEX;;;wEAGwE;AACxE,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,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5E;AACD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3E;AACD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhF;AACD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAE5E;AAED;;;2CAG2C;AAC3C,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,CA2CT;AAED;;oDAEoD;AACpD,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAqB1F;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

@@ -1,8 +1,7 @@
-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 };
+import { COLUMN_DESCRIPTOR_BYTES, COLUMN_DESCRIPTOR_OFFSETS, ARCHETYPE_DESCRIPTOR_HEADER_BYTES, LEGACY_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, LEGACY_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]`. */
+ * `TypedArrayTag` union, so a tag's element width is `TYPE_TAG_STRIDE[tag]`. */
 export declare const TYPE_TAG: {
     readonly u8: 0;
     readonly i8: 1;
@@ -18,9 +17,9 @@ export type TypeTagValue = (typeof TYPE_TAG)[keyof typeof TYPE_TAG];
  * `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
+ * 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
+ * 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;
@@ -36,18 +35,19 @@ 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. */
+    /** Byte offset of the column's first row, measured from the store base.
+     * A reader adds the base it mounted the store at. */
     readonly byteOff: number;
-    /** Element width in bytes; should always equal `TYPE_TAG_STRIDE[type_tag]`. */
+    /** 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
+ * module 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
+ * 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. The mask is sized to
  * the `BitSet`'s `INITIAL_WORD_COUNT`, so a registry within the limit never
@@ -60,20 +60,37 @@ export interface ArchetypeDescriptor {
     readonly componentMask: readonly number[];
     readonly rowCount: number;
     readonly rowCapacity: number;
-    /** Enabled-row count `≤ row_count`. 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
+    /** Enabled-row count `≤ row_count`. A compute backend's per-row entity-scan
+     * loops 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;
+ * planning the layout descriptor region size up front.
+ *
+ * `headerBytes` selects the header width and defaults to the current one. Pass
+ * `LEGACY_ARCHETYPE_DESCRIPTOR_HEADER_BYTES` to measure a version 0 region.
+ * Never pass it when planning a region the store will write. */
+export declare function archetypeDescriptorBytes(columnCount: number, headerBytes?: number): number;
 export declare function writeArchetypeDescriptor(view: DataView, off: number, d: ArchetypeDescriptor): number;
-export declare function readArchetypeDescriptor(view: DataView, off: number): ArchetypeDescriptor;
+/** Read one archetype descriptor at `off`.
+ *
+ * `headerBytes` says where this record's columns start and defaults to the
+ * current header width. A version 0 region needs
+ * `LEGACY_ARCHETYPE_DESCRIPTOR_HEADER_BYTES`, because it holds no
+ * `entity_ids_off`. Every other field sits at the same offset in both widths,
+ * so nothing else here branches on the version. */
+export declare function readArchetypeDescriptor(view: DataView, off: number, headerBytes?: 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[];
+/** Walk `archetypeCount` descriptors from `regionOff`, in written order.
+ *
+ * `headerBytes` selects the archetype header width, and defaults to the current
+ * one. A caller that reads a version 0 store passes
+ * `LEGACY_ARCHETYPE_DESCRIPTOR_HEADER_BYTES`, because the record stride is the
+ * only thing the narrower header changes. */
+export declare function readLayoutDescriptorRegion(view: DataView, regionOff: number, archetypeCount: number, headerBytes?: 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;

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

@@ -1,8 +1,7 @@
-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 };
+import { COLUMN_DESCRIPTOR_BYTES, COLUMN_DESCRIPTOR_OFFSETS, ARCHETYPE_DESCRIPTOR_HEADER_BYTES, LEGACY_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, LEGACY_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]`. */
+ * `TypedArrayTag` union, so a tag's element width is `TYPE_TAG_STRIDE[tag]`. */
 export declare const TYPE_TAG: {
     readonly u8: 0;
     readonly i8: 1;
@@ -18,9 +17,9 @@ export type TypeTagValue = (typeof TYPE_TAG)[keyof typeof TYPE_TAG];
  * `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
+ * 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
+ * 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;
@@ -36,18 +35,19 @@ 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. */
+    /** Byte offset of the column's first row, measured from the store base.
+     * A reader adds the base it mounted the store at. */
     readonly byteOff: number;
-    /** Element width in bytes; should always equal `TYPE_TAG_STRIDE[type_tag]`. */
+    /** 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
+ * module 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
+ * 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. The mask is sized to
  * the `BitSet`'s `INITIAL_WORD_COUNT`, so a registry within the limit never
@@ -60,20 +60,37 @@ export interface ArchetypeDescriptor {
     readonly componentMask: readonly number[];
     readonly rowCount: number;
     readonly rowCapacity: number;
-    /** Enabled-row count `≤ row_count`. 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
+    /** Enabled-row count `≤ row_count`. A compute backend's per-row entity-scan
+     * loops 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;
+ * planning the layout descriptor region size up front.
+ *
+ * `headerBytes` selects the header width and defaults to the current one. Pass
+ * `LEGACY_ARCHETYPE_DESCRIPTOR_HEADER_BYTES` to measure a version 0 region.
+ * Never pass it when planning a region the store will write. */
+export declare function archetypeDescriptorBytes(columnCount: number, headerBytes?: number): number;
 export declare function writeArchetypeDescriptor(view: DataView, off: number, d: ArchetypeDescriptor): number;
-export declare function readArchetypeDescriptor(view: DataView, off: number): ArchetypeDescriptor;
+/** Read one archetype descriptor at `off`.
+ *
+ * `headerBytes` says where this record's columns start and defaults to the
+ * current header width. A version 0 region needs
+ * `LEGACY_ARCHETYPE_DESCRIPTOR_HEADER_BYTES`, because it holds no
+ * `entity_ids_off`. Every other field sits at the same offset in both widths,
+ * so nothing else here branches on the version. */
+export declare function readArchetypeDescriptor(view: DataView, off: number, headerBytes?: 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[];
+/** Walk `archetypeCount` descriptors from `regionOff`, in written order.
+ *
+ * `headerBytes` selects the archetype header width, and defaults to the current
+ * one. A caller that reads a version 0 store passes
+ * `LEGACY_ARCHETYPE_DESCRIPTOR_HEADER_BYTES`, because the record stride is the
+ * only thing the narrower header changes. */
+export declare function readLayoutDescriptorRegion(view: DataView, regionOff: number, archetypeCount: number, headerBytes?: 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;

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

@@ -1 +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"}
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../../src/core/store/descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAYH,OAAO,EACN,uBAAuB,EACvB,yBAAyB,EACzB,iCAAiC,EACjC,wCAAwC,EACxC,4BAA4B,EAC5B,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,uBAAuB,EACvB,yBAAyB,EACzB,iCAAiC,EACjC,wCAAwC,EACxC,4BAA4B,EAC5B,oBAAoB,EACpB,CAAC;AAEF;gFACgF;AAChF,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;AAWX,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;yDACqD;IACrD,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;AAkBD;;;;;;;;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;;;;;gEAKgE;AAChE,wBAAgB,wBAAwB,CACvC,WAAW,EAAE,MAAM,EACnB,WAAW,GAAE,MAA0C,GACrD,MAAM,CAER;AAED,wBAAgB,wBAAwB,CACvC,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,MAAM,EACX,CAAC,EAAE,mBAAmB,GACpB,MAAM,CAyBR;AAED;;;;;;mDAMmD;AACnD,wBAAgB,uBAAuB,CACtC,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,MAAM,EACX,WAAW,GAAE,MAA0C,GACrD,mBAAmB,CAuBrB;AAcD,wBAAgB,2BAA2B,CAC1C,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,SAAS,mBAAmB,EAAE,GACzC,MAAM,CAMR;AAED;;;;;6CAK6C;AAC7C,wBAAgB,0BAA0B,CACzC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,WAAW,GAAE,MAA0C,GACrD,SAAS,mBAAmB,EAAE,CAShC;AAED;yEACyE;AACzE,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,GAAG,MAAM,CAM/F"}

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

@@ -1,18 +1,18 @@
 /**
- * Entity-index SAB region — `EntityID` → `(archetype_id, row, generation)`
- * lookup table shared with the Zig sim.
+ * Entity-index SAB region, `EntityID` → `(archetype_id, row, generation)`
+ * lookup table shared with a compute backend.
  *
- * 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. WASM-into-TS callbacks
- * during `tick()` are forbidden, so the lookup
+ * Every hot fixed-update system that resolves an `EntityID`
+ * held in a column (a component field that points at another
+ * entity, and through it at that entity's columns) has to do
+ * `entityId → archetype + row` translation. A WASM-into-TS callback
+ * during a tick is forbidden, 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)
+ *   [ capacity:  u32 ]   backing-array length (slots × 1, not bytes)
  *   [ _pad0:     u32 ]   alignment pad to 16 bytes
  *   [ _pad1:     u32 ]   ───
  *   [ generations[capacity]: i32 ]
@@ -21,26 +21,26 @@
  *
  * Sentinels:
  *   - `generations[i] = 0` (INITIAL_GENERATION) for never-used slots.
- *     Generation grows by 1 on every destroy; an `EntityID`'s generation
+ *     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.
+ *     into an archetype, or when the entity is destroyed.
+ *   - `rows[i]      = -1` (`UNASSIGNED`) on a destroy, or when 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.
+ * `Int32Array` without unsigned coercion. A module reads i32 too. The bit
+ * pattern is identical to u32 `0xFFFFFFFF` for the `UNASSIGNED` case, and
+ * for a valid archetype id (bounded by `MAX_INDEX`) the sign bit
+ * is never set, so signed and unsigned interpretation agree.
  *
  * Region placement: between command ring and descriptor region so the
- * offset is stable across descriptor / column-region growth (same
+ * offset is stable across descriptor growth and column-region growth (same
  * property the command ring gets). Grow path (when entityHighWater
- * exceeds `capacity`) uses `growColumnStore` — slow path, same as
+ * 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.
+ * A module reads the region with the symmetric reader: the header first,
+ * then the two i32 arrays it names.
  */
 /** Fixed bytes of the region header (length, capacity, two pad u32s for
  * 16-byte alignment of the i32 arrays that follow). */
@@ -48,24 +48,23 @@ 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
+ * `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.
+/** Default initial slot count when the engine creates a Store. It is
+ * `MAX_INDEX + 1`, the whole `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. That reservation is
+ * virtual memory only. Physical pages allocate lazily, through an OS page
+ * fault on first touch, so a small workload keeps a small resident footprint
+ * whatever the reservation is.
  *
- * 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. */
+ * A caller can pass a smaller `CreateColumnStoreOptions.entityIndexCapacity`
+ * for a tighter reservation. On-demand growth through `growColumnStore` would
+ * let the default 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;
@@ -81,7 +80,7 @@ export declare class EntityIndexError extends Error {
 /** 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
+ * SAB. Generation 0 is the INITIAL_GENERATION sentinel, archetype and 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). */
@@ -94,13 +93,13 @@ export declare function entityIndexCapacity(view: DataView, regionOff: number):
 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`
+ * 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): {
+ * read. V8 specialises `arr[i] = v` aggressively for typed arrays. */
+export declare function createEntityIndexViews(buffer: ArrayBufferLike, regionOff: number, capacity: number): {
     readonly generations: Int32Array;
     readonly archetypes: Int32Array;
     readonly rows: Int32Array;