@oasys/oecs 0.5.4 → 0.6.0

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

@@ -1,93 +1,110 @@
 /**
- * BufferAllocator — pluggable buffer source for the SAB layer.
+ * BufferAllocator, pluggable buffer source for the SAB layer.
  *
  * The engine has historically allocated its SAB as a fresh
  * `new SharedArrayBuffer(totalBytes)` inside `createColumnStore`.
  * A WASM backend needs the SAB to optionally be backed by a
- * `WebAssembly.Memory.buffer` instead, so the sim can read and write the live
+ * `WebAssembly.Memory.buffer` instead, so a compute backend can read and write the live
  * ECS columns through its own memory handle. This module abstracts the
  * "where does the buffer come from" decision behind a single function
  * type.
  *
  * Contract for every `BufferAllocator`:
  *   - Returns a `SharedArrayBuffer` of byteLength >= `bytes`.
- *   - MAY detach any prior buffer the implementation has handed out
+ *   - May detach any prior buffer the implementation has handed out
  *     (e.g., `WebAssembly.Memory.grow` detaches existing typed-array
- *     views into the previous buffer). Callers MUST snapshot any data
- *     they need to preserve BEFORE invoking the allocator.
- *   - Returned buffers MAY be larger than `bytes` (e.g., wasm-memory
+ *     views into the previous buffer). Callers must snapshot any data
+ *     they need to preserve before invoking the allocator.
+ *   - Returned buffers may be larger than `bytes` (e.g., wasm-memory
  *     rounds up to 64 KiB page boundaries). Callers must rely on the
- *     SAB header / descriptor for the canonical layout, not on
+ *     SAB header and descriptor for the canonical layout, not on
  *     `buffer.byteLength`.
  *
- * The default `DEFAULT_SAB_ALLOCATOR` does `new SharedArrayBuffer(bytes)`
- * — fast, allocation-per-call, prior buffers untouched. Production code
+ * The default `DEFAULT_SAB_ALLOCATOR` does `new SharedArrayBuffer(bytes)`,
+ * fast, allocation-per-call, prior buffers untouched. Production code
  * paths that don't care about wasm interop stay on this.
  *
  * `wasmMemoryAllocator(memory)` returns an allocator that grows the
  * given `WebAssembly.Memory` (in 64 KiB page increments) as needed and
  * returns its current buffer. Used by a host so the
- * engine's SAB IS the sim's memory.
+ * engine's SAB is the module's own memory.
  */
 /**
  * Source of `SharedArrayBuffer`s for the SAB layer. See the file header
- * for the contract — in particular, the detachment caveat for in-place
+ * for the contract, in particular, the detachment caveat for in-place
  * implementations.
  *
  * The optional `isInPlace` marker tells the SAB layer that
  * **TypedArray and DataView views built over a returned buffer remain
- * valid after a subsequent allocator call** — reads and writes through
+ * valid after a subsequent allocator call**, reads and writes through
  * the old views land on the same underlying memory the new buffer
  * exposes. The `extendColumnStore` fast path uses this hint to skip the
  * snapshot+restore + view-rebuild work that's only necessary when the
  * memory actually moves.
  *
- * Note: `isInPlace` does NOT promise the SAB *reference* stays
+ * `isInPlace` does not promise the SAB *reference* stays
  * identical. `growableSabAllocator` happens to return the same SAB
  * instance every time (`SharedArrayBuffer.prototype.grow` resizes in
- * place); `wasmMemoryAllocator` on shared `WebAssembly.Memory`
+ * place). `wasmMemoryAllocator` on shared `WebAssembly.Memory`
  * returns a *new* SAB ref after `memory.grow()`, but old views built
- * over the previous ref keep working — V8 keeps the underlying linear
- * memory mapped at the same address. Verified empirically (this branch,
- * Bun + V8): writes via an old `Int32Array(old_ref, off, len)` after
+ * over the previous ref keep working. V8 keeps the underlying linear
+ * memory mapped at the same address. Verified empirically on Bun and V8:
+ * writes via an old `Int32Array(old_ref, off, len)` after
  * `memory.grow()` are visible through a fresh view over the new ref,
- * and vice versa. Default allocator omits the marker;
+ * and vice versa. Default allocator omits the marker
  * `growableSabAllocator` and `wasmMemoryAllocator` set it.
  */
 export interface BufferAllocator {
     /** Returns a buffer of byteLength >= `bytes`. The historical name is
-     * "SAB", but the return is `ArrayBufferLike`: `growableSabAllocator` /
+     * "SAB", but the return is `ArrayBufferLike`. `growableSabAllocator` and
      * `wasmMemoryAllocator` produce a `SharedArrayBuffer` (the SAB profile),
-     * while `heapArraybufferAllocator` produces a plain fixed (non-resizable)
-     * `ArrayBuffer` reserved at the cap (the pure-TS heap profile — no
+     * while `heapArrayBufferAllocator` produces a plain fixed (non-resizable)
+     * `ArrayBuffer` reserved at the cap (the pure-TS heap profile, no
      * cross-origin isolation required). The store layer treats the backing
-     * uniformly; only the WASM/worker boundary narrows back to
+     * uniformly. Only the WASM or worker boundary narrows back to
      * `SharedArrayBuffer`. */
     (bytes: number): ArrayBufferLike;
     readonly isInPlace?: boolean;
+    /**
+     * The allocator reserves the whole cap in one buffer at the first call, and
+     * the buffer never grows.
+     *
+     * `byteLength` then holds the cap and not the used size, so the tail cursor
+     * for a new column region must come from the header `capacity` instead. See
+     * `tailCursorBytes`. An allocator that grows its buffer to the live extent
+     * omits this marker, because for it `byteLength` is the tail.
+     *
+     * This is a property of the allocator and not of the buffer class. The heap
+     * profile reserves a fixed `ArrayBuffer`, and `fixedSabAllocator` reserves a
+     * fixed `SharedArrayBuffer` for the same reason. Both need the same tail
+     * rule.
+     */
+    readonly reservedAtCap?: boolean;
 }
 /**
  * The only allocator shape a **live `Store`** accepts. The engine makes
- * "a live Store is backed by an in-place allocator" a correctness invariant —
+ * "a live Store is backed by an in-place allocator" a correctness invariant,
  * the flush loops hoist entity-index views across grows. This brand moves
- * that invariant from runtime convention to the type/construction boundary:
- * `growableSabAllocator` / `wasmMemoryAllocator` / `heapArraybufferAllocator`
- * return it; `DEFAULT_SAB_ALLOCATOR` keeps the wide `BufferAllocator` type and
- * therefore cannot typecheck where a live-Store backing is required. Non-in-place
- * allocators remain valid for snapshot/test sizing only. The brand says nothing
- * about *shared* vs *heap* backing — `heapArraybufferAllocator`'s fixed
- * `ArrayBuffer` is just as in-place as a growable SAB: it is reserved at the full
- * cap up front and never moves, so grow/extend relocate columns *within* it
- * (`copyWithin`) rather than resizing the buffer — existing views stay valid, the
- * same guarantee `SharedArrayBuffer.prototype.grow` gives by resizing in place.
+ * that invariant from runtime convention to the type and construction boundary.
+ * `growableSabAllocator`, `wasmMemoryAllocator` and `heapArrayBufferAllocator`
+ * return it. `DEFAULT_SAB_ALLOCATOR` keeps the wide `BufferAllocator` type, so
+ * it cannot typecheck where a live-Store backing is required. An allocator that
+ * is not in-place stays valid for snapshot or test sizing only.
+ *
+ * The brand says nothing about *shared* against *heap* backing.
+ * `heapArrayBufferAllocator`'s fixed `ArrayBuffer` is as in-place as a growable
+ * SAB. It is reserved at the full cap up front and never moves, so grow and
+ * extend relocate columns *within* it (`copyWithin`) rather than resizing the
+ * buffer. Existing views stay valid, the same guarantee
+ * `SharedArrayBuffer.prototype.grow` gives by resizing in place.
  */
 export type InPlaceBufferAllocator = BufferAllocator & {
     readonly isInPlace: true;
 };
 /**
  * Thrown when an allocator cannot satisfy a request because its by-design
- * byte ceiling is reached (the cap is a runaway-growth signal, not a
- * limit to paper over — there is deliberately no grow-beyond-cap fallback).
+ * byte ceiling is reached. The cap is a runaway-growth signal, not a limit to
+ * paper over, so there is deliberately no grow-beyond-cap fallback.
  * Typed so `Store`'s grow handler can recognise the cap case and re-throw
  * with the caller's declared sizing intent attached without ever
  * catching-to-recover.
@@ -105,8 +122,8 @@ export declare class StoreCapExceededError extends Error {
 /** Thrown when a **SAB-producing** allocator runs in an environment that
  * doesn't expose `SharedArrayBuffer`. The fix is environment-level (the host
  * must serve the page cross-origin isolated, or be a runtime like Bun that
- * exposes SAB unconditionally) — OR choose the pure-TS heap profile
- * (`memory: { heap: {} }` / `heapArraybufferAllocator`), which needs no SAB
+ * exposes SAB unconditionally). Or choose the pure-TS heap profile
+ * (`memory: { backing: "heap" }`, `heapArrayBufferAllocator`), which needs no SAB
  * and no cross-origin isolation. Lives on the allocator (not the store)
  * because the allocator is the only thing that constructs a SAB. */
 export declare class SabUnavailableError extends Error {
@@ -116,78 +133,80 @@ export declare class SabUnavailableError extends Error {
  * Allocate a fresh `SharedArrayBuffer` per call. Prior buffers are
  * untouched and remain valid for as long as the caller holds references.
  * This is the default used by `createColumnStore` when no allocator is
- * provided. Throws `SabUnavailableError` in a runtime without SAB — the
+ * provided. Throws `SabUnavailableError` in a runtime without SAB, the
  * availability check lives here (the SAB-producing seam), not in
  * `createColumnStore`, so a heap allocator never trips it.
  */
 export declare const DEFAULT_SAB_ALLOCATOR: BufferAllocator;
 /**
  * Allocator that backs the SAB by a single growable `SharedArrayBuffer`
- * (created with `{ maxByteLength: maxBytes }`). First call allocates;
- * subsequent calls `.grow(bytes)` the existing buffer and return it.
+ * (created with `{ maxByteLength: maxBytes }`). The first call allocates. A
+ * later call grows the existing buffer and returns it.
+ *
+ * JavaScriptCore pays for the growth. It has no fast store path for a
+ * TypedArray view over a growable `SharedArrayBuffer`. A column read costs what
+ * a fixed buffer costs, but every column write costs far more. A system that
+ * writes a column in a loop is thus much slower here than the same system on
+ * the heap profile. The cost is per access and not per byte, so a small world
+ * pays the same penalty as a large one. V8 shows no such difference at the time
+ * of measurement. Safari and Bun are JavaScriptCore.
+ *
+ * Use `fixedSabAllocator` if you need a shared buffer and your code runs on
+ * JavaScriptCore. It reserves the cap at construction and keeps the fast store
+ * path on both engine families. It gives up the growth, and nothing else.
  *
  * The `isInPlace` marker is set so `extendColumnStore` knows it can
- * reuse the buffer rather than allocating fresh and copying data —
+ * reuse the buffer rather than allocating fresh and copying data,
  * existing typed-array views built with explicit `(byteOffset, length)`
  * stay valid after `.grow()` in Bun + V8 (the underlying mapping extends
  * in place rather than relocating).
  *
- * Sizing: `maxBytes` is committed *virtual* memory, not resident RAM —
+ * Sizing: `maxBytes` is committed *virtual* memory, not resident ram,
  * physical pages fault in lazily as the SAB actually grows. A larger cap costs
  * more time per allocation than a smaller one, because V8 does per-byte
- * bookkeeping when it constructs the buffer. The cost increases with the cap, so
- * a 1 GiB cap is the slowest of the sizes we measured and a 1 MiB cap the
- * quickest. A caller with a bigger world can pass a larger cap; a caller that
- * stays under the 256 MiB default keeps the quicker Store construction.
+ * bookkeeping when it constructs the buffer. A caller with a bigger world can
+ * pass a larger cap. A caller that stays under the 256 MiB default keeps the
+ * quicker Store construction.
  *
- * THE 256 MiB DEFAULT IS A HARD DESIGN CEILING, NOT A SOFT TARGET — and
- * exceeding it is INTENDED to be fatal. There is deliberately no
+ * The 256 MiB default is a hard design ceiling, not a soft target, and
+ * exceeding it is intended to be fatal. There is deliberately no
  * grow-beyond-cap fallback or compaction pass (see the loud
  * note at the `bytes > maxBytes` throw below). If you are here because
  * a workload died at the cap and you are tempted to add a fresh-allocator
- * realloc fallback: don't, unless the numbers below have changed. They
- * say the cap is structurally unreachable for a real workload.
+ * realloc fallback: don't. The cap is structurally out of reach for a real
+ * workload.
  *
- * Measured footprint of a real 2-party workload (instrumented, 2026-05;
- * do NOT trust the old "~500 archetypes × 64-capacity ≈ 2 MiB" figure
- * that used to live here — it was wrong on every term):
- *   - Total SAB capacity ≈ 16.2 MiB — ~6% of the cap.
- *   - ~12 MiB of that is the entity-index region's *virtual* reservation
- *     (`ENTITY_INDEX_DEFAULT_CAPACITY = 1<<20` slots × 12 B); only ~12 KiB
- *     of it is physically resident for a 1000-entity workload.
- *   - Only ~5 archetypes are prewarmed (no lazy archetypes), each at
- *     `DEFAULT_COLUMN_CAPACITY = 1024` rows — NOT 64. Live column data is
- *     ~0.1 MiB; a fully-populated entity row is ~49 B.
- *   - Columns never trigger a grow: 1024 initial capacity already covers the
- *     ~1000-row budget, so the doubling + in-place hole tax never fires on
- *     the hot path.
- * The entity-ID space itself caps total live entities at `1<<20` ≈ 1M
- * (20-bit index in `EntityID`). Even at that absolute ceiling — ~1M rows
- * × 49 B × ~3 (post-double capacity + abandoned holes) ≈ ~150 MiB columns
- * + 12 MiB index — the workload still lands under 256 MiB. You cannot reach
- * the cap without first exhausting the entity-ID space. Hitting it
- * therefore signals a real defect upstream (runaway entity creation), not
- * a sizing shortfall to paper over.
+ * Why it is out of reach. The entity-index region dominates the footprint, and
+ * it is a virtual reservation of `ENTITY_INDEX_DEFAULT_CAPACITY` (1<<20) slots
+ * of `ENTITY_INDEX_BYTES_PER_SLOT` each, of which only the touched pages are
+ * resident. Live column data is a small part beside it, because an archetype
+ * is prewarmed at `DEFAULT_COLUMN_CAPACITY` rows and a real world stays inside
+ * that, so a column grow never fires on the hot path. The entity-id space caps
+ * live entities at `1<<20` (the 20-bit index in `EntityID`). Even at that
+ * ceiling, the columns plus the index still land under the default cap. You
+ * cannot reach the cap without first exhausting the entity-id space. Hitting
+ * it therefore signals a real defect upstream (runaway entity creation), not a
+ * sizing shortfall to paper over.
  *
  * Cited verification: a Bun runtime check
  * confirms `new Int32Array(buffer, off, len)` retains identical byteOffset,
- * length, and stored values after `.grow()`; DataView byteLength
+ * length, and stored values after `.grow()`. DataView byteLength
  * auto-tracks the grown buffer.
  *
  * Used by the `extendColumnStore` fast path during lazy archetype
- * registration — keeps existing column views valid so
+ * registration, keeps existing column views valid so
  * `refreshViews` is a no-op for old archetypes.
  */
 export declare function growableSabAllocator(maxBytes?: number): InPlaceBufferAllocator;
 /**
  * Allocator that backs the store by a single **fixed (non-resizable) plain
  * `ArrayBuffer`** reserved at the full `maxBytes` cap up front. This is the
- * pure-TS **heap profile** — the oecs default: no `SharedArrayBuffer`,
+ * pure-TS **heap profile**, the oecs default: no `SharedArrayBuffer`,
  * hence no cross-origin isolation
- * (COOP/COEP) requirement, and no worker/WASM transfer (single-process worlds
+ * (COOP and COEP) requirement, and no worker or WASM transfer (single-process worlds
  * only).
  *
- * WHY FIXED, NOT RESIZABLE (the 0.5.3 iteration-perf fix): V8 has no fast
+ * Why fixed, not resizable (the 0.5.3 iteration-perf fix): V8 has no fast
  * element-access path for TypedArray views over a **resizable or growable**
  * `ArrayBuffer`, because each `col[i]` reads the mutable length again. Thus a
  * loop over a column is much slower than the same loop over a fixed buffer.
@@ -197,48 +216,83 @@ export declare function growableSabAllocator(maxBytes?: number): InPlaceBufferAl
  *
  * How growth still works in place: the cap is reserved as one fixed buffer at
  * construction. A resizable buffer was originally chosen so `.resize()` could
- * grow in place without moving views; a fixed buffer never moves EITHER — the
- * store's grow/extend relocate columns to the tail *within* this buffer
+ * grow in place without moving views. A fixed buffer never moves either, the
+ * store's grow and extend relocate columns to the tail *within* this buffer
  * (`copyWithin`), so the buffer object and every existing view stay valid.
  * `isInPlace: true` therefore still holds, and the
  * entity-index-hoist-across-grow invariant is preserved. The store keys its
- * tail cursor off the header `capacity` (the logical high-water), NOT
- * `buffer.byteLength` — which is now always `maxBytes` (the same decoupling the
+ * tail cursor off the header `capacity` (the logical high-water), not
+ * `buffer.byteLength`, which is now always `maxBytes` (the same decoupling the
  * wasm page-rounded allocator already relied on).
  *
  *   - Memory cost is unchanged: a fixed `ArrayBuffer(maxBytes)` faults pages in
  *     lazily (untouched pages cost no RSS), exactly like the resizable buffer's
- *     `maxByteLength` reservation — a 256 MiB reservation on a 1000-entity world
- *     stays a few MiB resident (measured ~4 MiB RSS, within ~1 MiB of the old
- *     resizable buffer).
+ *     `maxByteLength` reservation. A large reservation on a small world stays
+ *     small in resident memory, the same as the old resizable buffer.
  *   - same 256 MiB default cap with hard-ceiling semantics: a request
- *     past `maxBytes` throws `StoreCapExceededError` — runaway growth signal,
+ *     past `maxBytes` throws `StoreCapExceededError`, runaway growth signal,
  *     not a limit to route around.
  *
  * Why a non-shared buffer suffices: `Atomics` live only on the cross-thread
- * command/event/action rings, never on the core store path, so a single-process
- * world needs no sharing. `stateHash` determinism works here too — FNV1a over
+ * command, event and action rings, never on the core store path, so a single-process
+ * world needs no sharing. `stateHash` determinism works here too. FNV1a over
  * column bytes is backing-agnostic.
  */
-export declare function heapArraybufferAllocator(maxBytes?: number): InPlaceBufferAllocator;
+export declare function heapArrayBufferAllocator(maxBytes?: number): InPlaceBufferAllocator;
 /**
- * Allocator that backs the SAB by `memory.buffer` — i.e. makes the engine's
+ * Allocator that backs the store by a single **fixed (non-growable)
+ * `SharedArrayBuffer`** reserved at the full `maxBytes` cap up front. This is
+ * the shared profile without the growth, and it exists for one measured
+ * reason.
+ *
+ * Why fixed, not growable: JavaScriptCore has no fast store path for a
+ * TypedArray view over a **growable** `SharedArrayBuffer`. A column read there
+ * costs what a fixed buffer costs, but every column write costs far
+ * more, so an iteration-bound system that updates a column is far slower on
+ * JavaScriptCore than the same system on the heap profile. Safari and Bun are
+ * JavaScriptCore. V8 shows no such difference at the time of measurement, so
+ * this is one engine family paying and the other not. A fixed buffer restores
+ * the fast store path on both.
+ *
+ * This is `heapArrayBufferAllocator` with a `SharedArrayBuffer` in place of the
+ * `ArrayBuffer`, and it keeps every property the shared profile needs: the
+ * buffer is shared, so a worker or a WASM module reads the same bytes, and it
+ * never moves, so views built over it stay valid. Growth still works the way
+ * the heap profile's does, the store relocates columns to the tail *within*
+ * the reserved buffer, and the tail comes from the header `capacity` because
+ * `reservedAtCap` says `byteLength` is the cap.
+ *
+ * The trade: the cap is reserved at construction instead of growing into. That
+ * is address space and not resident memory, the same as the heap profile's
+ * reservation.
+ */
+export declare function fixedSabAllocator(maxBytes?: number): InPlaceBufferAllocator;
+/**
+ * Allocator that backs the SAB by `memory.buffer`, i.e. makes the engine's
  * live SAB *be* a WASM module's `WebAssembly.Memory`. Grows the memory in
  * 64 KiB page increments when `bytes` exceeds the current buffer.
  *
+ * This backing is growable by nature. A shared `WebAssembly.Memory` gives a
+ * growable `SharedArrayBuffer` and can give nothing else. That looks like the
+ * shape `growableSabAllocator` warns about, and it is not. A probe measured a
+ * column write through a shared `WebAssembly.Memory` against the growable
+ * `SharedArrayBuffer` on JavaScriptCore and found no such cost. A WASM-backed
+ * world costs what the heap profile costs on every runtime tested, so
+ * `fixedSabAllocator` is no remedy here and none is needed.
+ *
  * This is the **opt-in storage backing for the WASM path**. A consumer
  * that attaches a WASM `ComputeBackend` passes
- * `bufferAllocator: wasmMemoryAllocator(memory)` so the Zig systems read/write
- * the same bytes the host's columns live in — zero-copy across the FFI boundary.
- * It is NOT a match-context assumption: a pure-TS game omits `bufferAllocator` and
- * gets the default (`DEFAULT_SAB_ALLOCATOR` — a fresh `SharedArrayBuffer` per
- * alloc) or opts into `growableSabAllocator` for the in-place fast path
- * without any WASM module. "The SAB is the WebAssembly.Memory" is thus a
+ * `bufferAllocator: wasmMemoryAllocator(memory)` so the module's systems read
+ * and write the same bytes the host's columns live in, zero-copy across the FFI
+ * boundary. A pure-TS world omits `bufferAllocator`
+ * and gets the default, `DEFAULT_SAB_ALLOCATOR`, a fresh `SharedArrayBuffer`
+ * per alloc. Or it opts into `growableSabAllocator` for the in-place fast path,
+ * with no WASM module at all. "The SAB is the WebAssembly.Memory" is thus a
  * property the WASM backend opts into, paid for only when WASM is in use.
  *
  * After `memory.grow()` on a *shared* memory, `memory.buffer` returns a
  * new `SharedArrayBuffer` reference, but **TypedArrays and DataViews
- * built over the previous reference remain valid** — V8 keeps the
+ * built over the previous reference remain valid**. V8 keeps the
  * underlying linear memory mapped at the same address, so reads and
  * writes through old views land on the same bytes the new buffer
  * exposes. This is why `isInPlace: true` is safe here (verified
@@ -249,7 +303,7 @@ export declare function heapArraybufferAllocator(maxBytes?: number): InPlaceBuff
  * construct a fresh DataView over the post-grow buffer (the SAB-layer
  * extend path does this).
  *
- * Throws if `memory` was not constructed with `shared: true` — the SAB
+ * Throws if `memory` was not constructed with `shared: true`, the SAB
  * contract requires `SharedArrayBuffer`-backed memory. Throws a contextual
  * error if a needed grow fails (cap reached or host refusal): the JS API's
  * `memory.grow` throws a RangeError on cap overrun rather than returning the