@oasys/oecs 0.5.3 → 0.6.0

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

@@ -5,14 +5,14 @@ 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. */
+/** 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. */
+/** 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. */
@@ -20,9 +20,10 @@ export interface ArchetypeSpec {
     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. */
+/** A single column's view after allocation. `byteOff` matches what the layout
+ * descriptor records, so it is measured from the store base. `view` is a
+ * TypedArray of the right element type, length `row_capacity`, and its
+ * `byteOffset` is `storeBase + byteOff`. */
 export interface ColumnView {
     readonly componentId: number;
     readonly fieldId: number;
@@ -35,7 +36,7 @@ export interface ColumnView {
  * 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
+ * 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
@@ -51,13 +52,20 @@ export interface ArchetypeViews {
 }
 export interface ColumnStore {
     /** The backing buffer. `ArrayBufferLike` because the store is backing-agnostic:
-     * a `SharedArrayBuffer` for the SAB/WASM/worker profile, or a plain fixed
-     * `ArrayBuffer` for the pure-TS heap profile (`heapArraybufferAllocator`).
-     * Consumers that genuinely require sharing (worker transfer, WASM memory)
-     * narrow back to `SharedArrayBuffer` at their boundary. */
+     * a `SharedArrayBuffer` for the SAB, WASM and worker profile, or a plain fixed
+     * `ArrayBuffer` for the pure-TS heap profile (`heapArrayBufferAllocator`).
+     * A consumer that genuinely requires sharing (worker transfer, WASM memory)
+     * narrows back to `SharedArrayBuffer` at its own boundary. */
     readonly buffer: ArrayBufferLike;
+    /** A `DataView` whose start is the store base, so every relative offset the
+     * header and the descriptors carry indexes it directly. */
     readonly view: DataView;
     readonly header: StoreHeader;
+    /** Byte offset of the header inside `buffer`. Every other offset in the
+     * store is relative to this. The store writes only inside
+     * `[storeBase, storeBase + header.capacity)`, which is what lets a WASM
+     * module own the bytes below the base. */
+    readonly storeBase: number;
     /** Indexed by `archetype_id`. */
     readonly archetypes: ReadonlyMap<number, ArchetypeViews>;
 }
@@ -82,46 +90,46 @@ export declare function columnKey(componentId: number, fieldId: number): number;
  * 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
+ * `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
+ * a real world far 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). */
+ * cap to stay in front of it. */
 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. */
+ * not the (tunable, much lower) 256 MiB allocator cap. */
 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).
+ * of two (1, 2, 4 or 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
+ * signed 32-bit int and wraps past 2³¹. 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.
+ * `stride` filled in) and return both them and the byte offset immediately 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
+ * `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
+ * the growable-SAB path, column views stay valid across
  * `extendColumnStore` because their byte_offs don't move.
  *
- * Additive, not a floor (#541): `regionSize = natural + headroom`, NOT
+ * Additive, not a floor: `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
+ * below it. The moment the descriptor region outgrows the floor (the
  * headroom exhausts and a realloc re-plans the merged spec set), a floor
- * would size the region to exactly `natural` — zero slack — and every
+ * 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
@@ -132,17 +140,17 @@ declare function planLayout(specs: readonly ArchetypeSpec[], regionOff: number,
     totalBytes: number;
     regionBytes: number;
 };
-/** Exported for the layout tests' overflow-guard coverage; the in-place
+/** 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).
+     * on top of the natural size for `specs` (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
+     * `growableSabAllocator` to give the in-place fast path: existing
      * TypedArray column views stay valid across extends because their offsets
      * and the underlying buffer both stay put.
      *
@@ -150,78 +158,98 @@ export interface CreateColumnStoreOptions {
      * 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). */
+     * going permanently slow. */
     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).
+    /** When provided, allocates a command ring inside
+     * the SAB at a stable offset right after the `STORE_HEADER_BYTES` 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"). An existing test fixture with a hand-rolled SAB
+     * sees the legacy layout, with the descriptor region right after the 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
+     * Sizing the ring this way, between header and descriptor region,
+     * keeps `command_ring_off` stable across an `extendColumnStore` or
+     * `growColumnStore` call, 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
+    /** When provided, allocates the entity-index region 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
+     * archetypes, rows)` triples indexed by entity slot. The engine's
+     * `Store` populates them as entities are created, moved and destroyed,
+     * and a compute backend reads 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
+     * `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)
+    /** When provided, allocates the event ring
      * 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.
+     * and the descriptor region. It has the same SPSC shape as the command
+     * ring. It carries ECS signal payloads, so a module's systems emit and
+     * consume them during a 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. */
+     * 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"). An existing test fixture with a hand-rolled
+     * SAB sees the layout without it. */
     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.
+    /** When provided, allocates the action ring
+     * inside the SAB at a stable offset between the entity-index and event-ring
+     * and the region-table directory. The main thread writes encoded actions to
+     * it, and the 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.) */
+     * 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"). A bare-SAB test skips 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
+    /** Consumer-declared SAB regions. 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. */
+     * snapshots and restores them across a grow or extend. The engine never
+     * interprets `region_id`. The consumer that declared the region 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:
+    /** Byte size of the always-before-descriptor sim-bindings region. A consumer
+     * that opts into a WASM backend supplies its own size here, computed from
+     * its own 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`.
+     * region, so the offset is stable across grow and extend) and the host
+     * writes the `(component_id, field_id)` ids into it.
      *
-     * 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
+     * Omitted or 0 ⇒ no bindings region (`bindings_off` stays 0, "absent"), the
+     * default for a pure-TS world that pays nothing for the WASM seam. This size
+     * used to be an engine-baked ABI constant reflected from the consumer's
+     * binding struct. It is now a runtime input, 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 and extend
      * without a carried policy field. */
     readonly bindingsRegionBytes?: number;
+    /** Byte offset inside the backing where the header goes. Default 0.
+     *
+     * Every offset the store writes is relative to this base, and the store
+     * writes only inside `[storeBase, storeBase + capacity)`. A WASM module owns
+     * the low addresses of its own linear memory, so a store mounted on that
+     * memory must stand above the module's data segment, its shadow stack and
+     * its heap base. A safe Zig or Rust build also traps on a read of address 0,
+     * so a module-hosted store cannot put the header there at all.
+     *
+     * Must be a non-negative integer and a multiple of
+     * `STORE_BASE_ALIGNMENT`, so every column keeps the alignment its type tag
+     * needs. */
+    readonly storeBase?: number;
 }
+/** Every store base must be a multiple of this. The widest column element is 8
+ * bytes, and the entity index wants 16, so 16 keeps both aligned whatever the
+ * base is. */
+export declare const STORE_BASE_ALIGNMENT = 16;
+/** Reject a base the layout math cannot honour. Cold path, one call per store
+ * creation. `resolveECSMemory` rejects the same values earlier with an
+ * `ECS_ERROR` code, so a world never reaches this. A direct store caller does. */
+export declare function assertStoreBase(storeBase: number): void;
 /** 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`,
@@ -230,44 +258,54 @@ 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`
+     * (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
+     * store that exhausts its headroom and reallocs keeps taking the
+     * in-place fast path instead of going permanently slow. The
      * `*_in_place` paths carry it forward verbatim. */
     readonly _reservedDescriptorBytes: number;
+    /** The descriptor-region bytes in use: the sum of `archetypeDescriptorBytes`
+     * over every archetype. The in-place extend reads it to find where the next
+     * descriptor goes and how much headroom remains. Cached here so an extend
+     * does not sum over every archetype each time, which made the cost of the
+     * N-th archetype grow with N. Absent on a record that predates the cache
+     * (a store from `growColumnStore`), and then summed one time on demand. */
+    readonly _usedDescriptorBytes?: number;
 }
-/** Typed recovery of `ColumnStoreInternal` from a public `ColumnStore` (M8).
+/** The descriptor-region bytes that `archetypes` use. */
+export declare function usedDescriptorBytes(archetypes: ReadonlyMap<number, ArchetypeViews>): number;
+/** Typed recovery of `ColumnStoreInternal` from a public `ColumnStore`.
  * 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
+ * allocator or headroom policy), and grow and extend must send such a store down
+ * the realloc slow path. This guard is the one place that discrimination
+ * happens, grow and 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.
+/** Allocate a backing sized for `specs` plus `options.storeBase`, write the
+ * header and the layout descriptor at the base, 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) */
+ * lives". Offsets in the bytes are relative to the base. `view_stamp` is
+ * initialised to 0, and a grow bumps it. */
 export declare function createColumnStore(specs: readonly ArchetypeSpec[], allocator?: BufferAllocator, options?: CreateColumnStoreOptions): ColumnStore;
-/** Default command-ring slot count used by `ECS.Store` when constructing
+/** Default command-ring slot count used by `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
+/** Default entity-index capacity used by `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
+/** Default event-ring slot count used by `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)
+/** Build the `ArchetypeViews` map from a backing and its parsed descriptors.
+ * Shared by `createColumnStore` (fresh allocation, byte_offs only 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>;
+ * snapshot). Either way each view lands at `storeBase` plus the descriptor's
+ * `byte_off`. This helper does not plan layout. */
+export declare function createArchetypeViews(buffer: ArrayBufferLike, storeBase: number, descriptors: readonly ArchetypeDescriptor[]): Map<number, ArchetypeViews>;
 //# sourceMappingURL=column_store.d.ts.map