@oasys/oecs 0.5.3 → 0.6.0

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

@@ -1,95 +1,112 @@
 /**
- * BufferAllocator — pluggable buffer source for the SAB layer (#234 / PR 3D).
+ * BufferAllocator, pluggable buffer source for the SAB layer.
  *
  * The engine has historically allocated its SAB as a fresh
  * `new SharedArrayBuffer(totalBytes)` inside `createColumnStore`.
- * Phase 3D requires the SAB to optionally be backed by a
- * `WebAssembly.Memory.buffer` so the WASM sim can read/write the live
+ * A WASM backend needs the SAB to optionally be backed by a
+ * `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 (#682). ADR-0008 makes
- * "a live Store is backed by an in-place allocator" a correctness invariant —
+ * The only allocator shape a **live `Store`** accepts. The engine makes
+ * "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 (#380: 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 (#682) without ever
+ * with the caller's declared sizing intent attached without ever
  * catching-to-recover.
  */
 export declare class StoreCapExceededError extends Error {
@@ -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,131 +133,166 @@ 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 —
- * physical pages fault in lazily as the SAB actually grows. Larger caps
- * cost more per allocation than smaller ones — Bun benchmark
- * `alloc(64,max=1GB)+grow(65568)` measures ~32 µs vs ~21 µs at 256 MB
- * and ~12 µs at 1 MB (V8 per-byte bookkeeping at construction).
- * Production callers with bigger worlds can pass a larger cap; the bench
- * gains are ~10 µs/Store-construction by staying under 256 MB.
+ * 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. 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
- * grow-beyond-cap fallback or compaction pass (see #380, and the loud
+ * 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 (#237 audit, this branch): Bun runtime check
+ * 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 (#237 Option A) — 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 and the answer to ADR-0018's
- * deferred §1B: no `SharedArrayBuffer`, hence no cross-origin isolation
- * (COOP/COEP) requirement, and no worker/WASM transfer (single-process worlds
+ * pure-TS **heap profile**, the oecs default: no `SharedArrayBuffer`,
+ * hence no cross-origin isolation
+ * (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
- * element-access path for TypedArray views over a **resizable/growable**
- * `ArrayBuffer` — every `col[i]` re-checks bounds against the buffer's mutable
- * length, a ~4× per-element tax measured on V8 13.6 (an isolated `col[i] *= 2`
- * loop: fixed `ArrayBuffer` ~1.6G vs a view over a resizable buffer ~0.37G
- * element-accesses/s). oecs 0.3.x gave each column its own fixed buffer and sat
- * mid-pack among SoA ECS libs; the 0.5.0 switch to one resizable arena silently
- * regressed all iteration-bound systems ~5× (the cross-library `packed_5`
- * scenario: 0.5.2 ~86k op/s → 0.5.3 ~420k). A fixed buffer restores the fast path.
+ * 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.
+ * Version 0.3.x gave each column its own fixed buffer. The change in 0.5.0 to
+ * one resizable arena made every iteration-bound system slower, and it gave no
+ * signal. A fixed buffer restores the fast path.
  *
  * 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 ADR-0008's
+ * `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).
- *   - same 256 MiB default cap with hard-ceiling semantics (#380): a request
- *     past `maxBytes` throws `StoreCapExceededError` — runaway growth signal,
+ *     `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,
  *     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 is the **opt-in storage backing for the WASM path** (#625). A consumer
+ * 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
@@ -251,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

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

@@ -1 +1 @@
-{"version":3,"file":"allocator.d.ts","sourceRoot":"","sources":["../../../src/core/store/allocator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;;;8BAO0B;IAC1B,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,sBAAsB,GAAG,eAAe,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC;AAEpF;;;;;;;GAOG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAG9B,cAAc,EAAE,MAAM;IACtC;6DACyD;aACzC,QAAQ,EAAE,MAAM,GAAG,IAAI;gBAJvC,OAAO,EAAE,MAAM,EACC,cAAc,EAAE,MAAM;IACtC;6DACyD;IACzC,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvC,OAAO,CAAC,EAAE,YAAY;CAKvB;AAED;;;;;;oEAMoE;AACpE,qBAAa,mBAAoB,SAAQ,KAAK;;CAe7C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,eAGnC,CAAC;AAgEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,GAAE,MAA0B,GAAG,sBAAsB,CA6BjG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,wBAAwB,CACvC,QAAQ,GAAE,MAA0B,GAClC,sBAAsB,CAsBxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,GAAG,sBAAsB,CA6DtF"}
+{"version":3,"file":"allocator.d.ts","sourceRoot":"","sources":["../../../src/core/store/allocator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;;;8BAO0B;IAC1B,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,sBAAsB,GAAG,eAAe,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC;AAEpF;;;;;;;GAOG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAG9B,cAAc,EAAE,MAAM;IACtC;6DACyD;aACzC,QAAQ,EAAE,MAAM,GAAG,IAAI;gBAJvC,OAAO,EAAE,MAAM,EACC,cAAc,EAAE,MAAM;IACtC;6DACyD;IACzC,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvC,OAAO,CAAC,EAAE,YAAY;CAKvB;AAED;;;;;;oEAMoE;AACpE,qBAAa,mBAAoB,SAAQ,KAAK;;CAe7C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,eAGnC,CAAC;AAsEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,GAAE,MAA0B,GAAG,sBAAsB,CA6BjG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,wBAAwB,CACvC,QAAQ,GAAE,MAA0B,GAClC,sBAAsB,CAuBxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,MAA0B,GAAG,sBAAsB,CAqB9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,GAAG,sBAAsB,CA4DtF"}

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

@@ -1,9 +1,9 @@
 import { ColumnBacking } from '../../type_primitives/index.cjs';
 import { AnyTypedArray } from './column_store.cjs';
-/** Thrown when an operation would grow a fixed-capacity SAB column. The
- * grow path (re-allocate the SAB, bump `view_stamp`, rebuild views) is a
- * separate sub-task; until it lands, hitting capacity is a hard error so
- * the symptom surfaces immediately rather than silently corrupting state. */
+/** Thrown when an operation would grow a fixed-capacity SAB column. The column
+ * does not own its buffer, so it cannot grow. The store's grow path
+ * (`growColumnStore`, then `refreshView`) is the only way capacity rises, and
+ * this throw makes a missed grow surface at once rather than corrupt state. */
 export declare class StoreColumnOverflowError extends Error {
     readonly capacity: number;
     readonly requested: number;
@@ -13,25 +13,25 @@ export declare class BufferBackedColumn<T extends AnyTypedArray> implements Colu
     private _buf;
     private _capacity;
     private _len;
-    /** `view` MUST be a TypedArray constructed over a SAB at the correct
+    /** `view` must be a TypedArray constructed over a SAB at the correct
      * stride alignment (see `createColumnStore`). The column treats
-     * `view.length` as the immutable capacity for the lifetime of this view —
+     * `view.length` as the immutable capacity for the lifetime of this view,
      * call `refreshView` after a SAB realloc to point at the new view. */
     constructor(view: T);
     /** Swap the backing view to one over a freshly-grown SAB. The caller is
      * responsible for having copied the first `length` elements into
      * `newView` already (`growColumnStore` does this). The logical length is
-     * preserved across the swap; capacity becomes `newView.length`.
+     * preserved across the swap. Capacity becomes `newView.length`.
      *
-     * Used to honour the `view_stamp` invariant after a host-side SAB realloc
-     * (#171 §6.1.4 / §8.1): every cached column view must be rebuilt before
-     * the next read/write. */
+     * Used to honour the `view_stamp` invariant after a host-side SAB realloc:
+     * every cached column view must be rebuilt before
+     * the next read or write. */
     refreshView(newView: T): void;
     get length(): number;
     get capacity(): number;
     push(value: number): void;
     pop(): number;
-    get(i: number): number;
+    getAt(i: number): number;
     setAt(i: number, value: number): void;
     /** Move the last element into slot `i`, decrement length. Returns the
      * value previously at slot `i`. Matches `GrowableTypedArray.swapRemove`. */
@@ -39,24 +39,23 @@ export declare class BufferBackedColumn<T extends AnyTypedArray> implements Colu
     clear(): void;
     /** Set the logical length directly, declaring that `[0, len)` of the backing
      * SAB view already holds valid data. The snapshot-mount path
-     * (`Archetype.restoreHostRows`, #789) uses this to re-sync the column's
-     * logical length with the restored `Archetype.length` — the bytes come from
+     * (`Archetype.restoreHostRows`) uses this to re-sync the column's
+     * logical length with the restored `Archetype.length`, the bytes come from
      * the restored SAB, but `_len` is host state. Throws on overrun (cannot grow
-     * a fixed SAB view here — the mount already adopted the restored capacity). */
+     * a fixed SAB view here, the mount already adopted the restored capacity). */
     setLength(len: number): void;
-    /** Raw backing view. Stable for the lifetime of the SAB; views over a
+    /** Raw backing view. Stable for the lifetime of the SAB. Views over a
      * SAB do not invalidate the way a `GrowableTypedArray`'s `buf` does
-     * after a grow. (`view_stamp` will signal "underlying SAB swapped"
-     * once #171 §6.1.4 lands.) */
+     * after a grow. (`view_stamp` signals "underlying SAB swapped".) */
     get buf(): T;
     /** Zero-copy subarray of valid data (`0..length-1`). */
     view(): T;
     [Symbol.iterator](): Iterator<number>;
-    /** Throw if the backing view cannot hold `capacity` elements. Mirrors
-     * `GrowableTypedArray.ensureCapacity` but cannot allocate — a SAB
-     * grow requires republishing the underlying buffer and rebuilding views
-     * across every archetype, which is the §6.1.4 invariant. */
-    ensureCapacity(capacity: number): void;
+    /** Throw if the view cannot hold `capacity` elements. The column does not own
+     * its buffer, so it cannot grow: a grow reallocates the store buffer and
+     * rebuilds the views of every archetype, which is the republish invariant.
+     * The allocator drives that path, and this method refuses it. */
+    reserve(capacity: number): void;
     /** Append `count` elements from `src[srcOffset..srcOffset+count]`.
      * Throws on overrun. */
     bulkAppend(src: T, srcOffset: number, count: number): void;

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

@@ -1,9 +1,9 @@
 import { ColumnBacking } from '../../type_primitives/index.js';
 import { AnyTypedArray } from './column_store.js';
-/** Thrown when an operation would grow a fixed-capacity SAB column. The
- * grow path (re-allocate the SAB, bump `view_stamp`, rebuild views) is a
- * separate sub-task; until it lands, hitting capacity is a hard error so
- * the symptom surfaces immediately rather than silently corrupting state. */
+/** Thrown when an operation would grow a fixed-capacity SAB column. The column
+ * does not own its buffer, so it cannot grow. The store's grow path
+ * (`growColumnStore`, then `refreshView`) is the only way capacity rises, and
+ * this throw makes a missed grow surface at once rather than corrupt state. */
 export declare class StoreColumnOverflowError extends Error {
     readonly capacity: number;
     readonly requested: number;
@@ -13,25 +13,25 @@ export declare class BufferBackedColumn<T extends AnyTypedArray> implements Colu
     private _buf;
     private _capacity;
     private _len;
-    /** `view` MUST be a TypedArray constructed over a SAB at the correct
+    /** `view` must be a TypedArray constructed over a SAB at the correct
      * stride alignment (see `createColumnStore`). The column treats
-     * `view.length` as the immutable capacity for the lifetime of this view —
+     * `view.length` as the immutable capacity for the lifetime of this view,
      * call `refreshView` after a SAB realloc to point at the new view. */
     constructor(view: T);
     /** Swap the backing view to one over a freshly-grown SAB. The caller is
      * responsible for having copied the first `length` elements into
      * `newView` already (`growColumnStore` does this). The logical length is
-     * preserved across the swap; capacity becomes `newView.length`.
+     * preserved across the swap. Capacity becomes `newView.length`.
      *
-     * Used to honour the `view_stamp` invariant after a host-side SAB realloc
-     * (#171 §6.1.4 / §8.1): every cached column view must be rebuilt before
-     * the next read/write. */
+     * Used to honour the `view_stamp` invariant after a host-side SAB realloc:
+     * every cached column view must be rebuilt before
+     * the next read or write. */
     refreshView(newView: T): void;
     get length(): number;
     get capacity(): number;
     push(value: number): void;
     pop(): number;
-    get(i: number): number;
+    getAt(i: number): number;
     setAt(i: number, value: number): void;
     /** Move the last element into slot `i`, decrement length. Returns the
      * value previously at slot `i`. Matches `GrowableTypedArray.swapRemove`. */
@@ -39,24 +39,23 @@ export declare class BufferBackedColumn<T extends AnyTypedArray> implements Colu
     clear(): void;
     /** Set the logical length directly, declaring that `[0, len)` of the backing
      * SAB view already holds valid data. The snapshot-mount path
-     * (`Archetype.restoreHostRows`, #789) uses this to re-sync the column's
-     * logical length with the restored `Archetype.length` — the bytes come from
+     * (`Archetype.restoreHostRows`) uses this to re-sync the column's
+     * logical length with the restored `Archetype.length`, the bytes come from
      * the restored SAB, but `_len` is host state. Throws on overrun (cannot grow
-     * a fixed SAB view here — the mount already adopted the restored capacity). */
+     * a fixed SAB view here, the mount already adopted the restored capacity). */
     setLength(len: number): void;
-    /** Raw backing view. Stable for the lifetime of the SAB; views over a
+    /** Raw backing view. Stable for the lifetime of the SAB. Views over a
      * SAB do not invalidate the way a `GrowableTypedArray`'s `buf` does
-     * after a grow. (`view_stamp` will signal "underlying SAB swapped"
-     * once #171 §6.1.4 lands.) */
+     * after a grow. (`view_stamp` signals "underlying SAB swapped".) */
     get buf(): T;
     /** Zero-copy subarray of valid data (`0..length-1`). */
     view(): T;
     [Symbol.iterator](): Iterator<number>;
-    /** Throw if the backing view cannot hold `capacity` elements. Mirrors
-     * `GrowableTypedArray.ensureCapacity` but cannot allocate — a SAB
-     * grow requires republishing the underlying buffer and rebuilding views
-     * across every archetype, which is the §6.1.4 invariant. */
-    ensureCapacity(capacity: number): void;
+    /** Throw if the view cannot hold `capacity` elements. The column does not own
+     * its buffer, so it cannot grow: a grow reallocates the store buffer and
+     * rebuilds the views of every archetype, which is the republish invariant.
+     * The allocator drives that path, and this method refuses it. */
+    reserve(capacity: number): void;
     /** Append `count` elements from `src[srcOffset..srcOffset+count]`.
      * Throws on overrun. */
     bulkAppend(src: T, srcOffset: number, count: number): void;

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

@@ -1 +1 @@
-{"version":3,"file":"buffer_backed_column.d.ts","sourceRoot":"","sources":["../../../src/core/store/buffer_backed_column.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;6EAG6E;AAC7E,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEtB,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM/C;AAED,qBAAa,kBAAkB,CAAC,CAAC,SAAS,aAAa,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IACnF,OAAO,CAAC,IAAI,CAAI;IAChB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,IAAI,CAAK;IAEjB;;;0EAGsE;gBAC1D,IAAI,EAAE,CAAC;IAKnB;;;;;;;8BAO0B;IACnB,WAAW,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI;IAQpC,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAEM,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAOzB,GAAG,IAAI,MAAM;IAIb,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM;IAItB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAI5C;gFAC4E;IACrE,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM;IAM7B,KAAK,IAAI,IAAI;IAIpB;;;;;mFAK+E;IACxE,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOnC;;;kCAG8B;IAC9B,IAAW,GAAG,IAAI,CAAC,CAElB;IAED,wDAAwD;IACjD,IAAI,IAAI,CAAC;IAQhB,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC;IAYrC;;;gEAG4D;IACrD,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAM7C;4BACwB;IACjB,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAQjE,gDAAgD;IACzC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM5C;gEAC4D;IACrD,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CAK1D"}
+{"version":3,"file":"buffer_backed_column.d.ts","sourceRoot":"","sources":["../../../src/core/store/buffer_backed_column.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;+EAG+E;AAC/E,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEtB,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAQ/C;AAED,qBAAa,kBAAkB,CAAC,CAAC,SAAS,aAAa,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IACnF,OAAO,CAAC,IAAI,CAAI;IAChB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,IAAI,CAAK;IAEjB;;;0EAGsE;gBAC1D,IAAI,EAAE,CAAC;IAKnB;;;;;;;iCAO6B;IACtB,WAAW,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI;IAQpC,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAEM,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAOzB,GAAG,IAAI,MAAM;IAIb,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM;IAIxB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAI5C;gFAC4E;IACrE,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM;IAM7B,KAAK,IAAI,IAAI;IAIpB;;;;;kFAK8E;IACvE,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOnC;;wEAEoE;IACpE,IAAW,GAAG,IAAI,CAAC,CAElB;IAED,wDAAwD;IACjD,IAAI,IAAI,CAAC;IAQhB,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC;IAYrC;;;qEAGiE;IAC1D,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMtC;4BACwB;IACjB,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAQjE,gDAAgD;IACzC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM5C;gEAC4D;IACrD,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CAK1D"}