@oasys/oecs 0.3.1 → 0.5.0

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

@@ -0,0 +1,273 @@
+import { StoreHeader } from './header.cjs';
+import { ArchetypeDescriptor, TypeTagValue } from './descriptor.cjs';
+import { BufferAllocator } from './allocator.cjs';
+import { COMMAND_RING_DEFAULT_CAPACITY_SLOTS } from './command_ring.cjs';
+import { ENTITY_INDEX_DEFAULT_CAPACITY } from './entity_index.cjs';
+import { EVENT_RING_DEFAULT_CAPACITY_SLOTS } from './event_ring.cjs';
+import { StoreRegionSpec } from './region_table.cjs';
+/** Caller-facing column spec — no `byte_off` yet, the store computes it. */
+export interface ColumnSpec {
+    readonly componentId: number;
+    readonly fieldId: number;
+    readonly typeTag: TypeTagValue;
+}
+/** Caller-facing archetype spec — no `column_count` (derived) and no
+ * `byte_off`s in the columns; both are computed during sizing. */
+export interface ArchetypeSpec {
+    readonly archetypeId: number;
+    /** Component bitmask, `COMPONENT_MASK_WORDS` little-endian u32 words. */
+    readonly componentMask: readonly number[];
+    readonly rowCapacity: number;
+    readonly columns: readonly ColumnSpec[];
+}
+/** A single column's view after allocation. The `byte_off` matches what
+ * was recorded in the layout descriptor; `view` is a TypedArray of the
+ * right element type, length `row_capacity`, backed by the SAB. */
+export interface ColumnView {
+    readonly componentId: number;
+    readonly fieldId: number;
+    readonly typeTag: TypeTagValue;
+    readonly byteOff: number;
+    readonly stride: number;
+    readonly view: AnyTypedArray;
+}
+/** Views for all columns in a single archetype, indexed by a numeric
+ * key encoding `(component_id, field_id)` so a (cid, fid) pair maps to
+ * its column in O(1). The encoding (see `columnKey`) is dense over
+ * (cid: 0..65535, fid: 0..65535), letting V8 keep this as a
+ * Number-keyed `Map` — meaningfully faster than the previous string
+ * keys (no per-lookup template-string allocation, no string hashing).
+ * The row order matches `ArchetypeSpec.columns`. The
+ * `component_mask` words mirror what's in the SAB layout descriptor so
+ * `growColumnStore` (and any other carry-forward path) doesn't have to
+ * re-parse the descriptor region. */
+export interface ArchetypeViews {
+    readonly archetypeId: number;
+    /** Component bitmask, `COMPONENT_MASK_WORDS` little-endian u32 words. */
+    readonly componentMask: readonly number[];
+    readonly rowCapacity: number;
+    readonly columns: ReadonlyMap<number, ColumnView>;
+    readonly columnsInOrder: readonly ColumnView[];
+}
+export interface ColumnStore {
+    /** The backing buffer. `ArrayBufferLike` because the store is backing-agnostic:
+     * a `SharedArrayBuffer` for the SAB/WASM/worker profile, or a plain resizable
+     * `ArrayBuffer` for the pure-TS heap profile (`heapArraybufferAllocator`).
+     * Consumers that genuinely require sharing (worker transfer, WASM memory)
+     * narrow back to `SharedArrayBuffer` at their boundary. */
+    readonly buffer: ArrayBufferLike;
+    readonly view: DataView;
+    readonly header: StoreHeader;
+    /** Indexed by `archetype_id`. */
+    readonly archetypes: ReadonlyMap<number, ArchetypeViews>;
+}
+export type AnyTypedArray = Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array;
+/** Pack `(component_id, field_id)` into a single non-negative integer so
+ * `ArchetypeViews.columns` can be a `Map<number, ColumnView>` instead of
+ * `Map<string, ColumnView>`. V8's number-keyed `Map` skips the
+ * string-hash + string-equality every lookup pays, and template-string
+ * keys (`"${cid}:${fid}"`) allocated a fresh string on every call. On
+ * the lazy-registration ramp-up the per-extend `refreshViews`
+ * walks `N` × `cols` of these lookups for `N` archetypes, so the saving
+ * compounds quadratically.
+ *
+ * Encoding: `(component_id << 16) | field_id`. `component_id` is bounded
+ * by `STORE_DESCRIPTOR_COMPONENT_LIMIT` (the registration cap, 128), well
+ * below 65536. `field_id` is bounded by the component's schema width,
+ * single digits in practice. */
+export declare function columnKey(componentId: number, fieldId: number): number;
+/** First byte offset the SAB layout math cannot represent: 2³¹.
+ *
+ * `alignUp` rounds with `& ~(align-1)`, and JS bitwise operators coerce
+ * their operands to **signed** 32-bit integers (`ToInt32`). Once an offset
+ * reaches 2³¹ the result wraps to a negative number (or, for some inputs, a
+ * misaligned positive one), which then flows straight into
+ * `new Uint8Array(buffer, byte_off, …)` — either a thrown `RangeError` deep in
+ * the TypedArray ctor or, worse, a silently wrong view overlapping another
+ * column. The 256 MiB default allocator cap (`growableSabAllocator`) keeps
+ * real matches three orders of magnitude below this, but the cap is tunable
+ * and callers are invited to raise it for bigger worlds — so the layout step
+ * guards the hard 2³¹ ceiling explicitly rather than relying on the policy
+ * cap to stay in front of it (#382). */
+export declare const STORE_MAX_BYTE_OFFSET: number;
+/** Thrown when a SAB column layout would place an offset at or beyond
+ * {@link STORE_MAX_BYTE_OFFSET} (2³¹), past which the signed-32-bit bitwise
+ * `alignUp` can no longer produce correct offsets. This is a hard ceiling,
+ * not the (tunable, much lower) 256 MiB allocator cap — see #382. */
+export declare class StoreLayoutOverflowError extends Error {
+    constructor(byteOff: number);
+}
+/** Round `off` up to the next multiple of `align`. `align` must be a power
+ * of two (1/2/4/8 here, all `TYPE_TAG_STRIDE` values).
+ *
+ * Throws {@link StoreLayoutOverflowError} when the rounded offset would reach
+ * {@link STORE_MAX_BYTE_OFFSET}, because the `& ~(align-1)` step coerces to a
+ * signed 32-bit int and wraps past 2³¹ (#382). The guard fires before the
+ * bitwise op so any returned offset is always a correct, in-range value.
+ * Shared by `extend.ts` and `grow.ts`, whose in-place paths compute tail
+ * byte_offs without going through `planLayout`. */
+export declare function alignUp(off: number, align: number): number;
+/** Build the layout-descriptor-region descriptors (with `byte_off` and
+ * `stride` filled in) and return both them and the byte offset just past
+ * the last column — i.e. the total SAB size.
+ *
+ * `headroomBytes` reserves slack at the end of the descriptor region — ON
+ * TOP OF the natural size for `specs` — so future extends can append new
+ * descriptor entries without shifting existing column byte_offs. Used by
+ * the growable-SAB path (#237 Option A) — column views stay valid across
+ * `extendColumnStore` because their byte_offs don't move.
+ *
+ * Additive, not a floor (#541): `regionSize = natural + headroom`, NOT
+ * `max(natural, headroom)`. A floor only yields slack while `natural` is
+ * below it; the moment the descriptor region outgrows the floor (the #237
+ * headroom exhausts and a realloc re-plans the merged spec set), a floor
+ * would size the region to exactly `natural` — zero slack — and every
+ * subsequent extend would take the slow realloc path forever after. The
+ * additive form re-creates the same `headroom` margin on every realloc.
+ * For the engine's empty-seed store (`createColumnStore([], …)`, where
+ * `natural === 0`) the two forms coincide, so this is behaviour-identical
+ * for the only production caller. */
+declare function planLayout(specs: readonly ArchetypeSpec[], regionOff: number, headroomBytes?: number): {
+    descriptors: ArchetypeDescriptor[];
+    totalBytes: number;
+    regionBytes: number;
+};
+/** Exported for the layout tests' overflow-guard coverage; the in-place
+ * resize paths use `layoutColumnsAtTail` (layout_ops.ts), not this. */
+export { planLayout };
+/** Optional configuration for `createColumnStore`. */
+export interface CreateColumnStoreOptions {
+    /** Extra slack to reserve at the end of the layout descriptor region,
+     * ON TOP OF the natural size for `specs` (#541 — additive, not a floor).
+     * The descriptor region is padded with this many unused bytes so future
+     * `extendColumnStore` calls can append new archetype descriptors into the
+     * slack without shifting existing column byte_offs. Pairs with
+     * `growableSabAllocator` to give the #237 Option A fast path: existing
+     * TypedArray column views stay valid across extends because their offsets
+     * and the underlying buffer both stay put.
+     *
+     * Carried forward as a policy across the realloc-and-republish path: the
+     * value lives on `ColumnStoreInternal._reservedDescriptorBytes` and
+     * `optionsFromOld` re-applies it, so a store that exhausts its headroom
+     * and reallocs gets a fresh margin rather than dropping to zero slack and
+     * going permanently slow (#541). */
+    readonly reservedDescriptorBytes?: number;
+    /** When provided, allocates a command ring (#171 §7.5, Phase 4) inside
+     * the SAB at a stable offset right after the 48-byte header. Slot
+     * count MUST be a power of two; `COMMAND_RING_DEFAULT_CAPACITY_SLOTS`
+     * (256) is the canonical value. Omitted ⇒ no ring; `command_ring_off`
+     * stays at 0 ("absent"); existing test fixtures with hand-rolled SABs
+     * see the legacy layout (descriptor region immediately after header).
+     *
+     * Sizing the ring this way — between header and descriptor region —
+     * keeps `command_ring_off` stable across `extendColumnStore` /
+     * `growColumnStore` calls, since those grow the descriptor region and
+     * the column tail but never the bytes between header and descriptor. */
+    readonly commandRingCapacitySlots?: number;
+    /** When provided, allocates the entity-index region (#245 / Phase 4
+     * PR 4B) inside the SAB at a stable offset between the command ring
+     * (or header) and the descriptor region. Holds `(generations,
+     * archetypes, rows)` triples indexed by entity slot; the engine's
+     * `Store` populates them as entities are created/moved/destroyed,
+     * and Zig systems read them to resolve cross-entity targets without
+     * a callback. Capacity is in *slots* (entities), not bytes; each
+     * slot is 12 bytes. Omitted ⇒ no region; `entity_index_off` stays
+     * at 0 ("absent"). The engine's Store always sets it to
+     * `ENTITY_INDEX_DEFAULT_CAPACITY`; bare-SAB tests can leave it
+     * absent. */
+    readonly entityIndexCapacity?: number;
+    /** When provided, allocates the event ring (#247 / Phase 4 PR 4C)
+     * inside the SAB at a stable offset between the entity-index region
+     * and the descriptor region. Same SPSC shape as the command ring;
+     * carries ECS signal payloads so Zig systems can emit and consume
+     * them during `tick()` without callbacks into TS.
+     *
+     * Slot count MUST be a power of two; `EVENT_RING_DEFAULT_CAPACITY_SLOTS`
+     * (256) is the canonical value. Omitted ⇒ no ring; `event_ring_off`
+     * stays at 0 ("absent"); existing test fixtures with hand-rolled
+     * SABs see the pre-#247 layout. */
+    readonly eventRingCapacitySlots?: number;
+    /** When provided, allocates the action ring (#291 / Phase 5 PR 5L)
+     * inside the SAB at a stable offset between the entity-index/event-ring
+     * and the region-table directory. Main writes encoded actions to it;
+     * the sim worker drains them on each apply.
+     *
+     * Slot count MUST be a power of two; `ACTION_RING_DEFAULT_CAPACITY_SLOTS`
+     * (256) is the canonical value. Omitted ⇒ no ring; `action_ring_off`
+     * stays at 0 ("absent"); bare-SAB tests skip it. (Engine mechanism — the
+     * `Store` allocates one always-on; it is no longer a public ECS option.) */
+    readonly actionRingCapacitySlots?: number;
+    /** Consumer-declared SAB regions (#623). Each `StoreRegionSpec` carries an
+     * opaque `region_id`, a precomputed byte size, and an `init` closure; the
+     * engine lays them out after the mechanism regions, writes a generic
+     * region-table directory (`region_table.ts`) keyed by `region_id`, and
+     * snapshots/restores them across a grow/extend. The engine never
+     * interprets `region_id` — a game (e.g. `@internal/sim`'s region specs)
+     * owns it. Omitted ⇒ no consumer regions; `region_table_off` stays 0. */
+    readonly regions?: readonly StoreRegionSpec[];
+    /** Byte size of the always-before-descriptor sim-bindings region (v5 /
+     * "SAB-is-the-interface"). A consumer that opts into a WASM backend supplies
+     * its own size here — `@internal/sim`'s `SIM_BINDINGS_BYTES`, computed from
+     * the game's binding manifest. The engine treats the region as opaque bytes:
+     * it reserves the block at `bindings_off` (right before the descriptor
+     * region, so the offset is stable across grow/extend) and the host writes the
+     * `(component_id, field_id)` IDs into it via `write_sim_bindings`.
+     *
+     * Omitted / 0 ⇒ NO bindings region (`bindings_off` stays 0, "absent") — the
+     * default for a pure-TS game that pays nothing for the WASM seam. This used
+     * to be the engine-baked `SIM_BINDINGS_BYTES` ABI constant reflected from the
+     * game's Zig struct; #625 de-welded it so a manifest edit no longer dirties
+     * the engine ABI golden. Re-derived across realloc by `optionsFromOld`
+     * (= `layout_descriptor_off - bindings_off`), so it survives grow/extend
+     * without a carried policy field. */
+    readonly bindingsRegionBytes?: number;
+}
+/** Internal `ColumnStore` extension carrying the descriptor-region byte
+ * size. Used by the in-place extend path to know where the next
+ * descriptor entry should be written (= `regionOff + region_bytes_used`,
+ * tracked separately) and how much headroom remains. */
+export interface ColumnStoreInternal extends ColumnStore {
+    readonly _regionBytes: number;
+    readonly _allocator: BufferAllocator;
+    /** The `reservedDescriptorBytes` policy this store was created with
+     * (the additive descriptor-region headroom margin; 0 when none). Carried
+     * with the store — NOT re-derivable from the SAB bytes, since `_regionBytes`
+     * holds the absolute region size (natural + this), and once `natural`
+     * outgrows the margin the two are indistinguishable. The realloc slow path
+     * reads it via `optionsFromOld` and re-reserves the same margin, so a
+     * store that exhausts its headroom and reallocs keeps taking the #237
+     * in-place fast path instead of going permanently slow (#541). The
+     * `*_in_place` paths carry it forward verbatim. */
+    readonly _reservedDescriptorBytes: number;
+}
+/** Typed recovery of `ColumnStoreInternal` from a public `ColumnStore` (M8).
+ * Not every store is internal: `restoreColumnStore` deliberately returns a
+ * plain `{ buffer, view, header, archetypes }` (a snapshot carries no JS-side
+ * allocator or headroom policy), and grow/extend must send such a store down
+ * the realloc slow path. This guard is the ONE place that discrimination
+ * happens — grow/extend previously re-derived the internal type via
+ * structural `as`-casts at six sites. */
+export declare function isColumnStoreInternal(store: ColumnStore): store is ColumnStoreInternal;
+/** Allocate a SAB sized for `specs`, write the header + layout descriptor,
+ * and construct one TypedArray view per column.
+ *
+ * The returned `ColumnStore` is the source of truth for "where every column
+ * lives in this SAB". `view_stamp` is initialised to 0 — a Phase 4 SAB
+ * grow flow will bump it. (#171 §6.1.4 / §8.1) */
+export declare function createColumnStore(specs: readonly ArchetypeSpec[], allocator?: BufferAllocator, options?: CreateColumnStoreOptions): ColumnStore;
+/** Default command-ring slot count used by `ECS.Store` when constructing
+ * its SAB. Re-exported here so the Store doesn't reach across modules. */
+export { COMMAND_RING_DEFAULT_CAPACITY_SLOTS };
+/** Default entity-index capacity used by `ECS.Store` when constructing
+ * its SAB. Re-exported alongside `COMMAND_RING_DEFAULT_CAPACITY_SLOTS`. */
+export { ENTITY_INDEX_DEFAULT_CAPACITY };
+/** Default event-ring slot count used by `ECS.Store` when constructing
+ * its SAB. Re-exported alongside the other defaults. */
+export { EVENT_RING_DEFAULT_CAPACITY_SLOTS };
+/** Build the `ArchetypeViews` map from a SAB and its parsed descriptors.
+ * Shared by `createColumnStore` (fresh allocation, byte_offs just computed)
+ * and `restoreColumnStore` (existing allocation, byte_offs read out of the
+ * snapshot). Either way the views land at the byte_offs the descriptors
+ * already carry — this helper does not plan layout. */
+export declare function buildArchetypeViews(buffer: ArrayBufferLike, descriptors: readonly ArchetypeDescriptor[]): Map<number, ArchetypeViews>;
+//# sourceMappingURL=column_store.d.ts.map

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

@@ -0,0 +1,273 @@
+import { StoreHeader } from './header.js';
+import { ArchetypeDescriptor, TypeTagValue } from './descriptor.js';
+import { BufferAllocator } from './allocator.js';
+import { COMMAND_RING_DEFAULT_CAPACITY_SLOTS } from './command_ring.js';
+import { ENTITY_INDEX_DEFAULT_CAPACITY } from './entity_index.js';
+import { EVENT_RING_DEFAULT_CAPACITY_SLOTS } from './event_ring.js';
+import { StoreRegionSpec } from './region_table.js';
+/** Caller-facing column spec — no `byte_off` yet, the store computes it. */
+export interface ColumnSpec {
+    readonly componentId: number;
+    readonly fieldId: number;
+    readonly typeTag: TypeTagValue;
+}
+/** Caller-facing archetype spec — no `column_count` (derived) and no
+ * `byte_off`s in the columns; both are computed during sizing. */
+export interface ArchetypeSpec {
+    readonly archetypeId: number;
+    /** Component bitmask, `COMPONENT_MASK_WORDS` little-endian u32 words. */
+    readonly componentMask: readonly number[];
+    readonly rowCapacity: number;
+    readonly columns: readonly ColumnSpec[];
+}
+/** A single column's view after allocation. The `byte_off` matches what
+ * was recorded in the layout descriptor; `view` is a TypedArray of the
+ * right element type, length `row_capacity`, backed by the SAB. */
+export interface ColumnView {
+    readonly componentId: number;
+    readonly fieldId: number;
+    readonly typeTag: TypeTagValue;
+    readonly byteOff: number;
+    readonly stride: number;
+    readonly view: AnyTypedArray;
+}
+/** Views for all columns in a single archetype, indexed by a numeric
+ * key encoding `(component_id, field_id)` so a (cid, fid) pair maps to
+ * its column in O(1). The encoding (see `columnKey`) is dense over
+ * (cid: 0..65535, fid: 0..65535), letting V8 keep this as a
+ * Number-keyed `Map` — meaningfully faster than the previous string
+ * keys (no per-lookup template-string allocation, no string hashing).
+ * The row order matches `ArchetypeSpec.columns`. The
+ * `component_mask` words mirror what's in the SAB layout descriptor so
+ * `growColumnStore` (and any other carry-forward path) doesn't have to
+ * re-parse the descriptor region. */
+export interface ArchetypeViews {
+    readonly archetypeId: number;
+    /** Component bitmask, `COMPONENT_MASK_WORDS` little-endian u32 words. */
+    readonly componentMask: readonly number[];
+    readonly rowCapacity: number;
+    readonly columns: ReadonlyMap<number, ColumnView>;
+    readonly columnsInOrder: readonly ColumnView[];
+}
+export interface ColumnStore {
+    /** The backing buffer. `ArrayBufferLike` because the store is backing-agnostic:
+     * a `SharedArrayBuffer` for the SAB/WASM/worker profile, or a plain resizable
+     * `ArrayBuffer` for the pure-TS heap profile (`heapArraybufferAllocator`).
+     * Consumers that genuinely require sharing (worker transfer, WASM memory)
+     * narrow back to `SharedArrayBuffer` at their boundary. */
+    readonly buffer: ArrayBufferLike;
+    readonly view: DataView;
+    readonly header: StoreHeader;
+    /** Indexed by `archetype_id`. */
+    readonly archetypes: ReadonlyMap<number, ArchetypeViews>;
+}
+export type AnyTypedArray = Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array;
+/** Pack `(component_id, field_id)` into a single non-negative integer so
+ * `ArchetypeViews.columns` can be a `Map<number, ColumnView>` instead of
+ * `Map<string, ColumnView>`. V8's number-keyed `Map` skips the
+ * string-hash + string-equality every lookup pays, and template-string
+ * keys (`"${cid}:${fid}"`) allocated a fresh string on every call. On
+ * the lazy-registration ramp-up the per-extend `refreshViews`
+ * walks `N` × `cols` of these lookups for `N` archetypes, so the saving
+ * compounds quadratically.
+ *
+ * Encoding: `(component_id << 16) | field_id`. `component_id` is bounded
+ * by `STORE_DESCRIPTOR_COMPONENT_LIMIT` (the registration cap, 128), well
+ * below 65536. `field_id` is bounded by the component's schema width,
+ * single digits in practice. */
+export declare function columnKey(componentId: number, fieldId: number): number;
+/** First byte offset the SAB layout math cannot represent: 2³¹.
+ *
+ * `alignUp` rounds with `& ~(align-1)`, and JS bitwise operators coerce
+ * their operands to **signed** 32-bit integers (`ToInt32`). Once an offset
+ * reaches 2³¹ the result wraps to a negative number (or, for some inputs, a
+ * misaligned positive one), which then flows straight into
+ * `new Uint8Array(buffer, byte_off, …)` — either a thrown `RangeError` deep in
+ * the TypedArray ctor or, worse, a silently wrong view overlapping another
+ * column. The 256 MiB default allocator cap (`growableSabAllocator`) keeps
+ * real matches three orders of magnitude below this, but the cap is tunable
+ * and callers are invited to raise it for bigger worlds — so the layout step
+ * guards the hard 2³¹ ceiling explicitly rather than relying on the policy
+ * cap to stay in front of it (#382). */
+export declare const STORE_MAX_BYTE_OFFSET: number;
+/** Thrown when a SAB column layout would place an offset at or beyond
+ * {@link STORE_MAX_BYTE_OFFSET} (2³¹), past which the signed-32-bit bitwise
+ * `alignUp` can no longer produce correct offsets. This is a hard ceiling,
+ * not the (tunable, much lower) 256 MiB allocator cap — see #382. */
+export declare class StoreLayoutOverflowError extends Error {
+    constructor(byteOff: number);
+}
+/** Round `off` up to the next multiple of `align`. `align` must be a power
+ * of two (1/2/4/8 here, all `TYPE_TAG_STRIDE` values).
+ *
+ * Throws {@link StoreLayoutOverflowError} when the rounded offset would reach
+ * {@link STORE_MAX_BYTE_OFFSET}, because the `& ~(align-1)` step coerces to a
+ * signed 32-bit int and wraps past 2³¹ (#382). The guard fires before the
+ * bitwise op so any returned offset is always a correct, in-range value.
+ * Shared by `extend.ts` and `grow.ts`, whose in-place paths compute tail
+ * byte_offs without going through `planLayout`. */
+export declare function alignUp(off: number, align: number): number;
+/** Build the layout-descriptor-region descriptors (with `byte_off` and
+ * `stride` filled in) and return both them and the byte offset just past
+ * the last column — i.e. the total SAB size.
+ *
+ * `headroomBytes` reserves slack at the end of the descriptor region — ON
+ * TOP OF the natural size for `specs` — so future extends can append new
+ * descriptor entries without shifting existing column byte_offs. Used by
+ * the growable-SAB path (#237 Option A) — column views stay valid across
+ * `extendColumnStore` because their byte_offs don't move.
+ *
+ * Additive, not a floor (#541): `regionSize = natural + headroom`, NOT
+ * `max(natural, headroom)`. A floor only yields slack while `natural` is
+ * below it; the moment the descriptor region outgrows the floor (the #237
+ * headroom exhausts and a realloc re-plans the merged spec set), a floor
+ * would size the region to exactly `natural` — zero slack — and every
+ * subsequent extend would take the slow realloc path forever after. The
+ * additive form re-creates the same `headroom` margin on every realloc.
+ * For the engine's empty-seed store (`createColumnStore([], …)`, where
+ * `natural === 0`) the two forms coincide, so this is behaviour-identical
+ * for the only production caller. */
+declare function planLayout(specs: readonly ArchetypeSpec[], regionOff: number, headroomBytes?: number): {
+    descriptors: ArchetypeDescriptor[];
+    totalBytes: number;
+    regionBytes: number;
+};
+/** Exported for the layout tests' overflow-guard coverage; the in-place
+ * resize paths use `layoutColumnsAtTail` (layout_ops.ts), not this. */
+export { planLayout };
+/** Optional configuration for `createColumnStore`. */
+export interface CreateColumnStoreOptions {
+    /** Extra slack to reserve at the end of the layout descriptor region,
+     * ON TOP OF the natural size for `specs` (#541 — additive, not a floor).
+     * The descriptor region is padded with this many unused bytes so future
+     * `extendColumnStore` calls can append new archetype descriptors into the
+     * slack without shifting existing column byte_offs. Pairs with
+     * `growableSabAllocator` to give the #237 Option A fast path: existing
+     * TypedArray column views stay valid across extends because their offsets
+     * and the underlying buffer both stay put.
+     *
+     * Carried forward as a policy across the realloc-and-republish path: the
+     * value lives on `ColumnStoreInternal._reservedDescriptorBytes` and
+     * `optionsFromOld` re-applies it, so a store that exhausts its headroom
+     * and reallocs gets a fresh margin rather than dropping to zero slack and
+     * going permanently slow (#541). */
+    readonly reservedDescriptorBytes?: number;
+    /** When provided, allocates a command ring (#171 §7.5, Phase 4) inside
+     * the SAB at a stable offset right after the 48-byte header. Slot
+     * count MUST be a power of two; `COMMAND_RING_DEFAULT_CAPACITY_SLOTS`
+     * (256) is the canonical value. Omitted ⇒ no ring; `command_ring_off`
+     * stays at 0 ("absent"); existing test fixtures with hand-rolled SABs
+     * see the legacy layout (descriptor region immediately after header).
+     *
+     * Sizing the ring this way — between header and descriptor region —
+     * keeps `command_ring_off` stable across `extendColumnStore` /
+     * `growColumnStore` calls, since those grow the descriptor region and
+     * the column tail but never the bytes between header and descriptor. */
+    readonly commandRingCapacitySlots?: number;
+    /** When provided, allocates the entity-index region (#245 / Phase 4
+     * PR 4B) inside the SAB at a stable offset between the command ring
+     * (or header) and the descriptor region. Holds `(generations,
+     * archetypes, rows)` triples indexed by entity slot; the engine's
+     * `Store` populates them as entities are created/moved/destroyed,
+     * and Zig systems read them to resolve cross-entity targets without
+     * a callback. Capacity is in *slots* (entities), not bytes; each
+     * slot is 12 bytes. Omitted ⇒ no region; `entity_index_off` stays
+     * at 0 ("absent"). The engine's Store always sets it to
+     * `ENTITY_INDEX_DEFAULT_CAPACITY`; bare-SAB tests can leave it
+     * absent. */
+    readonly entityIndexCapacity?: number;
+    /** When provided, allocates the event ring (#247 / Phase 4 PR 4C)
+     * inside the SAB at a stable offset between the entity-index region
+     * and the descriptor region. Same SPSC shape as the command ring;
+     * carries ECS signal payloads so Zig systems can emit and consume
+     * them during `tick()` without callbacks into TS.
+     *
+     * Slot count MUST be a power of two; `EVENT_RING_DEFAULT_CAPACITY_SLOTS`
+     * (256) is the canonical value. Omitted ⇒ no ring; `event_ring_off`
+     * stays at 0 ("absent"); existing test fixtures with hand-rolled
+     * SABs see the pre-#247 layout. */
+    readonly eventRingCapacitySlots?: number;
+    /** When provided, allocates the action ring (#291 / Phase 5 PR 5L)
+     * inside the SAB at a stable offset between the entity-index/event-ring
+     * and the region-table directory. Main writes encoded actions to it;
+     * the sim worker drains them on each apply.
+     *
+     * Slot count MUST be a power of two; `ACTION_RING_DEFAULT_CAPACITY_SLOTS`
+     * (256) is the canonical value. Omitted ⇒ no ring; `action_ring_off`
+     * stays at 0 ("absent"); bare-SAB tests skip it. (Engine mechanism — the
+     * `Store` allocates one always-on; it is no longer a public ECS option.) */
+    readonly actionRingCapacitySlots?: number;
+    /** Consumer-declared SAB regions (#623). Each `StoreRegionSpec` carries an
+     * opaque `region_id`, a precomputed byte size, and an `init` closure; the
+     * engine lays them out after the mechanism regions, writes a generic
+     * region-table directory (`region_table.ts`) keyed by `region_id`, and
+     * snapshots/restores them across a grow/extend. The engine never
+     * interprets `region_id` — a game (e.g. `@internal/sim`'s region specs)
+     * owns it. Omitted ⇒ no consumer regions; `region_table_off` stays 0. */
+    readonly regions?: readonly StoreRegionSpec[];
+    /** Byte size of the always-before-descriptor sim-bindings region (v5 /
+     * "SAB-is-the-interface"). A consumer that opts into a WASM backend supplies
+     * its own size here — `@internal/sim`'s `SIM_BINDINGS_BYTES`, computed from
+     * the game's binding manifest. The engine treats the region as opaque bytes:
+     * it reserves the block at `bindings_off` (right before the descriptor
+     * region, so the offset is stable across grow/extend) and the host writes the
+     * `(component_id, field_id)` IDs into it via `write_sim_bindings`.
+     *
+     * Omitted / 0 ⇒ NO bindings region (`bindings_off` stays 0, "absent") — the
+     * default for a pure-TS game that pays nothing for the WASM seam. This used
+     * to be the engine-baked `SIM_BINDINGS_BYTES` ABI constant reflected from the
+     * game's Zig struct; #625 de-welded it so a manifest edit no longer dirties
+     * the engine ABI golden. Re-derived across realloc by `optionsFromOld`
+     * (= `layout_descriptor_off - bindings_off`), so it survives grow/extend
+     * without a carried policy field. */
+    readonly bindingsRegionBytes?: number;
+}
+/** Internal `ColumnStore` extension carrying the descriptor-region byte
+ * size. Used by the in-place extend path to know where the next
+ * descriptor entry should be written (= `regionOff + region_bytes_used`,
+ * tracked separately) and how much headroom remains. */
+export interface ColumnStoreInternal extends ColumnStore {
+    readonly _regionBytes: number;
+    readonly _allocator: BufferAllocator;
+    /** The `reservedDescriptorBytes` policy this store was created with
+     * (the additive descriptor-region headroom margin; 0 when none). Carried
+     * with the store — NOT re-derivable from the SAB bytes, since `_regionBytes`
+     * holds the absolute region size (natural + this), and once `natural`
+     * outgrows the margin the two are indistinguishable. The realloc slow path
+     * reads it via `optionsFromOld` and re-reserves the same margin, so a
+     * store that exhausts its headroom and reallocs keeps taking the #237
+     * in-place fast path instead of going permanently slow (#541). The
+     * `*_in_place` paths carry it forward verbatim. */
+    readonly _reservedDescriptorBytes: number;
+}
+/** Typed recovery of `ColumnStoreInternal` from a public `ColumnStore` (M8).
+ * Not every store is internal: `restoreColumnStore` deliberately returns a
+ * plain `{ buffer, view, header, archetypes }` (a snapshot carries no JS-side
+ * allocator or headroom policy), and grow/extend must send such a store down
+ * the realloc slow path. This guard is the ONE place that discrimination
+ * happens — grow/extend previously re-derived the internal type via
+ * structural `as`-casts at six sites. */
+export declare function isColumnStoreInternal(store: ColumnStore): store is ColumnStoreInternal;
+/** Allocate a SAB sized for `specs`, write the header + layout descriptor,
+ * and construct one TypedArray view per column.
+ *
+ * The returned `ColumnStore` is the source of truth for "where every column
+ * lives in this SAB". `view_stamp` is initialised to 0 — a Phase 4 SAB
+ * grow flow will bump it. (#171 §6.1.4 / §8.1) */
+export declare function createColumnStore(specs: readonly ArchetypeSpec[], allocator?: BufferAllocator, options?: CreateColumnStoreOptions): ColumnStore;
+/** Default command-ring slot count used by `ECS.Store` when constructing
+ * its SAB. Re-exported here so the Store doesn't reach across modules. */
+export { COMMAND_RING_DEFAULT_CAPACITY_SLOTS };
+/** Default entity-index capacity used by `ECS.Store` when constructing
+ * its SAB. Re-exported alongside `COMMAND_RING_DEFAULT_CAPACITY_SLOTS`. */
+export { ENTITY_INDEX_DEFAULT_CAPACITY };
+/** Default event-ring slot count used by `ECS.Store` when constructing
+ * its SAB. Re-exported alongside the other defaults. */
+export { EVENT_RING_DEFAULT_CAPACITY_SLOTS };
+/** Build the `ArchetypeViews` map from a SAB and its parsed descriptors.
+ * Shared by `createColumnStore` (fresh allocation, byte_offs just computed)
+ * and `restoreColumnStore` (existing allocation, byte_offs read out of the
+ * snapshot). Either way the views land at the byte_offs the descriptors
+ * already carry — this helper does not plan layout. */
+export declare function buildArchetypeViews(buffer: ArrayBufferLike, descriptors: readonly ArchetypeDescriptor[]): Map<number, ArchetypeViews>;
+//# sourceMappingURL=column_store.d.ts.map

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

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

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

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