@oasys/oecs 0.5.3 → 0.6.0

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. (#245 / Phase 4 PR 4B)
+ * 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. The plan forbids
- * WASM-into-TS callbacks during `tick()` (§4 / §5.2), 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;

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

@@ -1,18 +1,18 @@
 /**
- * Entity-index SAB region — `EntityID` → `(archetype_id, row, generation)`
- * lookup table shared with the Zig sim. (#245 / Phase 4 PR 4B)
+ * 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. The plan forbids
- * WASM-into-TS callbacks during `tick()` (§4 / §5.2), 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;

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

@@ -1 +1 @@
-{"version":3,"file":"entity_index.d.ts","sourceRoot":"","sources":["../../../src/core/store/entity_index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH;uDACuD;AACvD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,yCAAyC;AACzC,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;6BAE6B;AAC7B,eAAO,MAAM,2BAA2B;;;CAI9B,CAAC;AAEX;;;;;;;;;;;qEAWqE;AACrE,eAAO,MAAM,6BAA6B,QAAU,CAAC;AAErD,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO/D;AAED,+DAA+D;AAC/D,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,8CAA8C;AAC9C,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,qCAAqC;AACrC,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI3B;AAED;;;;uEAIuE;AACvE,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACd,IAAI,CASN;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;aAEa;AACb,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAE5F;AAED;;;;;;;sEAOsE;AACtE,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACd;IACF,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC1B,CAQA"}
+{"version":3,"file":"entity_index.d.ts","sourceRoot":"","sources":["../../../src/core/store/entity_index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH;uDACuD;AACvD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,yCAAyC;AACzC,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;6BAE6B;AAC7B,eAAO,MAAM,2BAA2B;;;CAI9B,CAAC;AAEX;;;;;;;;;;2BAU2B;AAC3B,eAAO,MAAM,6BAA6B,QAAU,CAAC;AAErD,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO/D;AAED,+DAA+D;AAC/D,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,8CAA8C;AAC9C,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,qCAAqC;AACrC,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI3B;AAED;;;;uEAIuE;AACvE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAS/F;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;aAEa;AACb,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAE5F;AAED;;;;;;;sEAOsE;AACtE,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACd;IACF,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC1B,CAQA"}

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

@@ -1,68 +1,66 @@
 /**
- * Event ring — SPSC ring buffer for ECS signal/event payloads shared
- * between TS and the Zig sim. (#247 / Phase 4 PR 4C)
+ * Event ring. SPSC ring buffer for ECS signal and event payloads shared
+ * between TS and a compute backend.
  *
- * Same byte layout as the command ring (`command_ring.ts`); the two
- * could share a primitive but keeping them separate makes the
- * direction of flow explicit: command ring is WASM→TS (structural
- * intents to drain post-tick); event ring is bidirectional during
- * `tick()` — Zig systems push events, TS readers (or other Zig
- * systems) drain.
+ * Same byte layout as the command ring (`command_ring.ts`). The two
+ * could share a primitive, but keeping them separate makes the
+ * direction of flow explicit. The command ring is WASM→TS, and carries
+ * structural intents to drain post-tick. The event ring is bidirectional during
+ * a tick. A module's systems push events, and TS readers or sibling module
+ * systems drain.
  *
  * Layout (identical to command ring):
  *
- *   [ 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_flag: u32 ]   0 = OK; 1 = sticky overflow witness
+ *   [ overflow_flag: u32 ]   0 = OK, 1 = sticky overflow witness
  *   [ slot 0:        16 B ]  opCode: u8, payload: [15]u8
  *   [ slot 1:        16 B ]  ...
  *
- * Op codes: event-def IDs (assigned by `ECS.registerEvent()` at
- * registration time; #247 plan §required-FFI). The 0 op-code is
- * reserved as the empty-slot marker so a zero-initialised SAB does not
- * appear to hold a valid event. Event-def registration starts numbering
- * from 1 to honour this; the engine integration in 4D+ enforces it.
+ * Op codes: event-def ids, assigned when an event is registered. The 0
+ * op-code is reserved as the empty-slot marker so a zero-initialised SAB does
+ * not appear to hold a valid event. Event-def registration starts numbering
+ * from 1 to honour this.
  *
- * SPSC contract (Phase 4 scope, single host thread):
- *   - Producer: Zig sim `tick()` (post-4D) OR TS host (test producers /
- *     existing JS-side emitters bridged into the ring).
- *   - Consumer: TS host drain (post-4D) OR Zig system that reads
+ * SPSC contract (single host thread):
+ *   - Producer: a WASM tick, or the TS host (a test producer, or an
+ *     existing JS-side emitter bridged into the ring).
+ *   - Consumer: the TS host drain, or a module system that reads
  *     queued events from a sibling system.
- *   - 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
+ *   - 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.
  *
- * Payload size: fixed 15 bytes per slot. Today's events all fit
- * (e.g. a 12-byte 3-field event, a 4-byte 1-field event, a 0-field
- * signal). Larger payloads require a separate variable-size ring
- * design — out of scope here.
+ * Payload size: fixed 15 bytes per slot. Every event the engine carries today
+ * fits, because an event holds a few numeric fields at most. A larger payload
+ * needs a separate variable-size ring design, out of scope here.
  *
  * Region placement: between the entity-index region and the descriptor
- * region so its offset is stable across descriptor / column growth.
- * `header.event_ring_off` (the field promoted out of `_reserved0` in
- * #245's reservation) carries the offset; 0 means absent.
+ * region so its offset is stable across descriptor and column growth.
+ * `header.event_ring_off` (the field promoted out of `_reserved0`)
+ * carries the offset, 0 means absent.
  */
 /** Total bytes for the ring header. Matches command ring exactly. */
 export declare const EVENT_RING_HEADER_BYTES = 16;
-/** Fixed slot size — 1-byte opCode + 15-byte payload. Matches
+/** Fixed slot size, 1-byte opCode + 15-byte payload. Matches
  * command ring exactly. */
 export declare const EVENT_RING_SLOT_BYTES = 16;
 /** Default ring capacity in slots. 256 × 16 B = 4 KiB of slot data
  * plus 16 B header. Mirrors `COMMAND_RING_DEFAULT_CAPACITY_SLOTS`. */
 export declare const EVENT_RING_DEFAULT_CAPACITY_SLOTS = 256;
-/** Byte offsets within the ring header. Mirrored on the Zig side in
- * `packages/sim/src/event_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 EVENT_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 "empty slot"
- * (see file header). Event-def IDs start at 1; `ECS.registerEvent`
- * shifts to honour this when wiring SAB-backed channels in 4D+. */
+/** Op-code `0` is reserved across the SAB layer as "empty slot"
+ * (see file header). Event-def ids start at 1, so a SAB-backed channel never
+ * writes a code that reads as an empty slot. */
 export declare const EVENT_OP_EMPTY = 0;
 /** Total bytes the ring occupies for `capacity_slots` slots. */
 export declare function eventRingBytes(capacitySlots: number): number;
@@ -70,21 +68,21 @@ export declare class EventRingError 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 initEventRing(view: DataView, ringOff: number, capacitySlots: number): void;
-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 eventRingWriteHead(view: DataView, ringOff: number): number;
+export declare function eventRingReadHead(view: DataView, ringOff: number): number;
+export declare function eventRingCapacitySlots(view: DataView, ringOff: number): number;
+export declare function eventRingOverflow(view: DataView, ringOff: number): boolean;
 /** Pending event count = `(write_head - read_head) mod 2^32`. */
 export declare function pendingEventCount(view: DataView, ringOff: number): number;
 /** Push an event into the ring. Returns `false` on overflow and sets
- * the (sticky) overflow flag. `opCode` must be > 0 — 0 is reserved as
+ * the (sticky) overflow flag. `opCode` must be > 0, 0 is reserved as
  * the empty-slot marker. Payload must be exactly 15 bytes. */
 export declare function pushEvent(view: DataView, ringOff: number, opCode: number, payload: Uint8Array): boolean;
-/** Read one event from the ring. Returns opCode (0 = empty/no event)
+/** Read one event from the ring. Returns opCode (0 = empty, no event)
  * and fills `outPayload` with 15 bytes. When 0 is returned,
  * `outPayload` is untouched. */
 export declare function popEvent(view: DataView, ringOff: number, outPayload: Uint8Array): number;

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

@@ -1,68 +1,66 @@
 /**
- * Event ring — SPSC ring buffer for ECS signal/event payloads shared
- * between TS and the Zig sim. (#247 / Phase 4 PR 4C)
+ * Event ring. SPSC ring buffer for ECS signal and event payloads shared
+ * between TS and a compute backend.
  *
- * Same byte layout as the command ring (`command_ring.ts`); the two
- * could share a primitive but keeping them separate makes the
- * direction of flow explicit: command ring is WASM→TS (structural
- * intents to drain post-tick); event ring is bidirectional during
- * `tick()` — Zig systems push events, TS readers (or other Zig
- * systems) drain.
+ * Same byte layout as the command ring (`command_ring.ts`). The two
+ * could share a primitive, but keeping them separate makes the
+ * direction of flow explicit. The command ring is WASM→TS, and carries
+ * structural intents to drain post-tick. The event ring is bidirectional during
+ * a tick. A module's systems push events, and TS readers or sibling module
+ * systems drain.
  *
  * Layout (identical to command ring):
  *
- *   [ 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_flag: u32 ]   0 = OK; 1 = sticky overflow witness
+ *   [ overflow_flag: u32 ]   0 = OK, 1 = sticky overflow witness
  *   [ slot 0:        16 B ]  opCode: u8, payload: [15]u8
  *   [ slot 1:        16 B ]  ...
  *
- * Op codes: event-def IDs (assigned by `ECS.registerEvent()` at
- * registration time; #247 plan §required-FFI). The 0 op-code is
- * reserved as the empty-slot marker so a zero-initialised SAB does not
- * appear to hold a valid event. Event-def registration starts numbering
- * from 1 to honour this; the engine integration in 4D+ enforces it.
+ * Op codes: event-def ids, assigned when an event is registered. The 0
+ * op-code is reserved as the empty-slot marker so a zero-initialised SAB does
+ * not appear to hold a valid event. Event-def registration starts numbering
+ * from 1 to honour this.
  *
- * SPSC contract (Phase 4 scope, single host thread):
- *   - Producer: Zig sim `tick()` (post-4D) OR TS host (test producers /
- *     existing JS-side emitters bridged into the ring).
- *   - Consumer: TS host drain (post-4D) OR Zig system that reads
+ * SPSC contract (single host thread):
+ *   - Producer: a WASM tick, or the TS host (a test producer, or an
+ *     existing JS-side emitter bridged into the ring).
+ *   - Consumer: the TS host drain, or a module system that reads
  *     queued events from a sibling system.
- *   - 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
+ *   - 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.
  *
- * Payload size: fixed 15 bytes per slot. Today's events all fit
- * (e.g. a 12-byte 3-field event, a 4-byte 1-field event, a 0-field
- * signal). Larger payloads require a separate variable-size ring
- * design — out of scope here.
+ * Payload size: fixed 15 bytes per slot. Every event the engine carries today
+ * fits, because an event holds a few numeric fields at most. A larger payload
+ * needs a separate variable-size ring design, out of scope here.
  *
  * Region placement: between the entity-index region and the descriptor
- * region so its offset is stable across descriptor / column growth.
- * `header.event_ring_off` (the field promoted out of `_reserved0` in
- * #245's reservation) carries the offset; 0 means absent.
+ * region so its offset is stable across descriptor and column growth.
+ * `header.event_ring_off` (the field promoted out of `_reserved0`)
+ * carries the offset, 0 means absent.
  */
 /** Total bytes for the ring header. Matches command ring exactly. */
 export declare const EVENT_RING_HEADER_BYTES = 16;
-/** Fixed slot size — 1-byte opCode + 15-byte payload. Matches
+/** Fixed slot size, 1-byte opCode + 15-byte payload. Matches
  * command ring exactly. */
 export declare const EVENT_RING_SLOT_BYTES = 16;
 /** Default ring capacity in slots. 256 × 16 B = 4 KiB of slot data
  * plus 16 B header. Mirrors `COMMAND_RING_DEFAULT_CAPACITY_SLOTS`. */
 export declare const EVENT_RING_DEFAULT_CAPACITY_SLOTS = 256;
-/** Byte offsets within the ring header. Mirrored on the Zig side in
- * `packages/sim/src/event_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 EVENT_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 "empty slot"
- * (see file header). Event-def IDs start at 1; `ECS.registerEvent`
- * shifts to honour this when wiring SAB-backed channels in 4D+. */
+/** Op-code `0` is reserved across the SAB layer as "empty slot"
+ * (see file header). Event-def ids start at 1, so a SAB-backed channel never
+ * writes a code that reads as an empty slot. */
 export declare const EVENT_OP_EMPTY = 0;
 /** Total bytes the ring occupies for `capacity_slots` slots. */
 export declare function eventRingBytes(capacitySlots: number): number;
@@ -70,21 +68,21 @@ export declare class EventRingError 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 initEventRing(view: DataView, ringOff: number, capacitySlots: number): void;
-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 eventRingWriteHead(view: DataView, ringOff: number): number;
+export declare function eventRingReadHead(view: DataView, ringOff: number): number;
+export declare function eventRingCapacitySlots(view: DataView, ringOff: number): number;
+export declare function eventRingOverflow(view: DataView, ringOff: number): boolean;
 /** Pending event count = `(write_head - read_head) mod 2^32`. */
 export declare function pendingEventCount(view: DataView, ringOff: number): number;
 /** Push an event into the ring. Returns `false` on overflow and sets
- * the (sticky) overflow flag. `opCode` must be > 0 — 0 is reserved as
+ * the (sticky) overflow flag. `opCode` must be > 0, 0 is reserved as
  * the empty-slot marker. Payload must be exactly 15 bytes. */
 export declare function pushEvent(view: DataView, ringOff: number, opCode: number, payload: Uint8Array): boolean;
-/** Read one event from the ring. Returns opCode (0 = empty/no event)
+/** Read one event from the ring. Returns opCode (0 = empty, no event)
  * and fills `outPayload` with 15 bytes. When 0 is returned,
  * `outPayload` is untouched. */
 export declare function popEvent(view: DataView, ringOff: number, outPayload: Uint8Array): number;

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

@@ -1 +1 @@
-{"version":3,"file":"event_ring.d.ts","sourceRoot":"","sources":["../../../src/core/store/event_ring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;2BAC2B;AAC3B,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;sEACsE;AACtE,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAErD;uDACuD;AACvD,eAAO,MAAM,yBAAyB;;;;;CAK5B,CAAC;AAEX;;mEAEmE;AACnE,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE5D;AAMD,qBAAa,cAAe,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI3B;AAED;;;mCAGmC;AACnC,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAU1F;AAED,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,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED;;8DAE8D;AAC9D,wBAAgB,SAAS,CACxB,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,UAAU,GACjB,OAAO,CA4BT;AAED;;gCAEgC;AAChC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAiBxF;AAED;;iEAEiE;AACjE,wBAAgB,cAAc,CAC7B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,KAAK,IAAI,GACpD,MAAM,CASR"}
+{"version":3,"file":"event_ring.d.ts","sourceRoot":"","sources":["../../../src/core/store/event_ring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;2BAC2B;AAC3B,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;sEACsE;AACtE,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAErD;uDACuD;AACvD,eAAO,MAAM,yBAAyB;;;;;CAK5B,CAAC;AAEX;;gDAEgD;AAChD,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE5D;AAMD,qBAAa,cAAe,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI3B;AAED;;;mCAGmC;AACnC,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAU1F;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1E;AACD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE;AACD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9E;AACD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED;;8DAE8D;AAC9D,wBAAgB,SAAS,CACxB,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,UAAU,GACjB,OAAO,CAkCT;AAED;;gCAEgC;AAChC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAiBxF;AAED;;iEAEiE;AACjE,wBAAgB,cAAc,CAC7B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,KAAK,IAAI,GACpD,MAAM,CASR"}

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

@@ -2,23 +2,29 @@ import { ArchetypeSpec, ColumnStore } from './column_store.cjs';
 import { BufferAllocator } from './allocator.cjs';
 import { ArchetypeGrowSpec } from './layout_ops.cjs';
 export interface ExtendPlan {
-    /** Archetypes to append. Each `archetype_id` MUST be absent from
-     * `old.archetypes`; collisions throw `StoreExtendError`. */
+    /** Archetypes to append. Each `archetype_id` must be absent from
+     * `old.archetypes`. Collisions throw `StoreExtendError`. */
     readonly newArchetypes: readonly ArchetypeSpec[];
     /** Per-existing-archetype live row counts. Same shape as
      * `GrowPlan.archetypes` so callers can reuse plan-building helpers.
-     * Omitted or `0` ⇒ no rows to copy (the archetype is empty). */
-    readonly existing?: readonly ArchetypeGrowSpec[];
+     * Omitted or `0` ⇒ no rows to copy (the archetype is empty).
+     *
+     * Only the realloc path reads it: the in-place path moves no rows. A
+     * caller that must walk every archetype to build the list can pass a
+     * function instead, and the list is then built only when the realloc path
+     * runs. The in-place path is the common one, and a list built for every
+     * extend made the cost of the N-th archetype grow with N. */
+    readonly existing?: readonly ArchetypeGrowSpec[] | (() => readonly ArchetypeGrowSpec[]);
 }
 export interface ExtendResult {
     readonly store: ColumnStore;
     readonly oldViewStamp: number;
     readonly newViewStamp: number;
-    /** True when the in-place fast path (#237 Option A) was taken: the SAB
+    /** True when the in-place fast path was taken: the SAB
      * instance is reused, existing column TypedArray views are unchanged,
      * and callers may skip `refreshViews` on every pre-existing
      * Archetype. False when the slow path ran (fresh SAB or wasm-memory
-     * grow with detached views); callers MUST refresh every Archetype's
+     * grow with detached views). A caller must then refresh every Archetype's
      * SAB-backed columns from the returned `store` before reading them. */
     readonly viewsPreserved: boolean;
 }
@@ -28,12 +34,12 @@ export declare class StoreExtendError extends Error {
 /** Allocate a new SAB sized for `old` + `plan.newArchetypes`, copy
  * existing rows, bump `view_stamp`.
  *
- * `allocator` (PR 3D / #234): pluggable buffer source forwarded into
+ * `allocator`: pluggable buffer source forwarded into
  * `createColumnStore`. When the allocator is `wasmMemoryAllocator`,
  * `memory.grow` may detach `old`'s typed-array views before the copy
- * runs — so live rows are snapshotted into heap `Uint8Array`s BEFORE the
+ * runs, so live rows are snapshotted into heap `Uint8Array`s before the
  * allocator call and restored into the new views afterwards. The cost
- * is one extra heap allocation per live archetype-column; negligible
+ * is one extra heap allocation per live archetype-column. Negligible
  * compared to the SAB walk itself. */
 export declare function extendColumnStore(old: ColumnStore, plan: ExtendPlan, allocator?: BufferAllocator): ExtendResult;
 //# sourceMappingURL=extend.d.ts.map