@oasys/oecs 0.5.3 → 0.6.0

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

@@ -1,62 +1,59 @@
 /**
- * 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`).
+ * 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 (Phase 4 scope):
- *   - Producer: WASM `sim.tick()`. Pushes 0..N commands during one tick;
+ * SPSC contract (single host thread):
+ *   - 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.
- *   - 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
+ *     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
  *     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 (plan §7.5):
+ * 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 Phase 4 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;
@@ -65,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;
@@ -75,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,62 +1,59 @@
 /**
- * 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`).
+ * 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 (Phase 4 scope):
- *   - Producer: WASM `sim.tick()`. Pushes 0..N commands during one tick;
+ * SPSC contract (single host thread):
+ *   - 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.
- *   - 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
+ *     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
  *     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 (plan §7.5):
+ * 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 Phase 4 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;
@@ -65,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;
@@ -75,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"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,20 +35,21 @@ 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 (#381). The mask is sized to
+ * 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
  * grows a component mask past its initial words. */
 export declare const STORE_DESCRIPTOR_COMPONENT_LIMIT: number;
@@ -60,20 +60,37 @@ export interface ArchetypeDescriptor {
     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
+    /** 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,20 +35,21 @@ 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 (#381). The mask is sized to
+ * 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
  * grows a component mask past its initial words. */
 export declare const STORE_DESCRIPTOR_COMPONENT_LIMIT: number;
@@ -60,20 +60,37 @@ export interface ArchetypeDescriptor {
     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
+    /** 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"}