@oasys/oecs 0.3.1 → 0.5.0

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

@@ -0,0 +1,238 @@
+/**
+ * BufferAllocator — pluggable buffer source for the SAB layer (#234 / PR 3D).
+ *
+ * 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
+ * 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
+ *     (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
+ *     rounds up to 64 KiB page boundaries). Callers must rely on the
+ *     SAB header / 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
+ * 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.
+ */
+/**
+ * Source of `SharedArrayBuffer`s for the SAB layer. See the file header
+ * 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
+ * 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
+ * identical. `growableSabAllocator` happens to return the same SAB
+ * instance every time (`SharedArrayBuffer.prototype.grow` resizes in
+ * 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
+ * `memory.grow()` are visible through a fresh view over the new ref,
+ * 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` /
+     * `wasmMemoryAllocator` produce a `SharedArrayBuffer` (the SAB profile),
+     * while `heapArraybufferAllocator` produces a plain resizable
+     * `ArrayBuffer` (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 `SharedArrayBuffer`. */
+    (bytes: number): ArrayBufferLike;
+    readonly isInPlace?: 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 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 resizable
+ * `ArrayBuffer` is just as in-place as a growable SAB (`.resize()` preserves
+ * existing views exactly like `SharedArrayBuffer.prototype.grow`).
+ */
+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).
+ * 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
+ * catching-to-recover.
+ */
+export declare class StoreCapExceededError extends Error {
+    readonly requestedBytes: number;
+    /** `null` when the ceiling isn't knowable from JS (a shared
+     * `WebAssembly.Memory` doesn't expose its `maximum`). */
+    readonly capBytes: number | null;
+    constructor(message: string, requestedBytes: number, 
+    /** `null` when the ceiling isn't knowable from JS (a shared
+     * `WebAssembly.Memory` doesn't expose its `maximum`). */
+    capBytes: number | null, options?: ErrorOptions);
+}
+/** 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
+ * 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 {
+    constructor();
+}
+/**
+ * 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
+ * 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.
+ *
+ * The `isInPlace` marker is set so `extendColumnStore` knows it can
+ * 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.
+ *
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * Cited verification (#237 audit, this branch): Bun runtime check
+ * confirms `new Int32Array(buffer, off, len)` retains identical byteOffset,
+ * 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
+ * `refreshViews` is a no-op for old archetypes.
+ */
+export declare function growableSabAllocator(maxBytes?: number): InPlaceBufferAllocator;
+/**
+ * Allocator that backs the store by a single growable **plain `ArrayBuffer`**
+ * (created with `{ maxByteLength: maxBytes }`, grown via `.resize()`). 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
+ * only). Otherwise identical to `growableSabAllocator`:
+ *
+ *   - `isInPlace: true`. A resizable `ArrayBuffer`'s `.resize()` keeps the
+ *     same buffer object and preserves existing TypedArray/DataView views, so
+ *     the store's `extend`/`grow` fast path carries column views forward
+ *     unchanged — exactly as `SharedArrayBuffer.prototype.grow` does. ADR-0008's
+ *     entity-index-hoist-across-grow invariant holds identically.
+ *   - same 256 MiB default cap with hard-ceiling semantics (#380): reaching it
+ *     signals runaway growth upstream, 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
+ * column bytes is backing-agnostic.
+ */
+export declare function heapArraybufferAllocator(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
+ * 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
+ * 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
+ * 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
+ * empirically against Bun + V8): the SAB layer's fast path can carry
+ * forward existing column views across an `extend` without paying for
+ * snapshot+restore. Old DataViews' `byteLength` is frozen at the
+ * pre-grow size, so callers needing to write past that boundary must
+ * 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
+ * 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
+ * core wasm instruction's `-1`, and both are normalised into that error. The
+ * caller should construct memory with a `maximum` large enough for the
+ * workload's worst-case capacity.
+ */
+export declare function wasmMemoryAllocator(memory: WebAssembly.Memory): InPlaceBufferAllocator;
+//# sourceMappingURL=allocator.d.ts.map

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

@@ -0,0 +1,238 @@
+/**
+ * BufferAllocator — pluggable buffer source for the SAB layer (#234 / PR 3D).
+ *
+ * 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
+ * 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
+ *     (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
+ *     rounds up to 64 KiB page boundaries). Callers must rely on the
+ *     SAB header / 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
+ * 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.
+ */
+/**
+ * Source of `SharedArrayBuffer`s for the SAB layer. See the file header
+ * 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
+ * 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
+ * identical. `growableSabAllocator` happens to return the same SAB
+ * instance every time (`SharedArrayBuffer.prototype.grow` resizes in
+ * 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
+ * `memory.grow()` are visible through a fresh view over the new ref,
+ * 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` /
+     * `wasmMemoryAllocator` produce a `SharedArrayBuffer` (the SAB profile),
+     * while `heapArraybufferAllocator` produces a plain resizable
+     * `ArrayBuffer` (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 `SharedArrayBuffer`. */
+    (bytes: number): ArrayBufferLike;
+    readonly isInPlace?: 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 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 resizable
+ * `ArrayBuffer` is just as in-place as a growable SAB (`.resize()` preserves
+ * existing views exactly like `SharedArrayBuffer.prototype.grow`).
+ */
+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).
+ * 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
+ * catching-to-recover.
+ */
+export declare class StoreCapExceededError extends Error {
+    readonly requestedBytes: number;
+    /** `null` when the ceiling isn't knowable from JS (a shared
+     * `WebAssembly.Memory` doesn't expose its `maximum`). */
+    readonly capBytes: number | null;
+    constructor(message: string, requestedBytes: number, 
+    /** `null` when the ceiling isn't knowable from JS (a shared
+     * `WebAssembly.Memory` doesn't expose its `maximum`). */
+    capBytes: number | null, options?: ErrorOptions);
+}
+/** 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
+ * 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 {
+    constructor();
+}
+/**
+ * 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
+ * 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.
+ *
+ * The `isInPlace` marker is set so `extendColumnStore` knows it can
+ * 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.
+ *
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * Cited verification (#237 audit, this branch): Bun runtime check
+ * confirms `new Int32Array(buffer, off, len)` retains identical byteOffset,
+ * 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
+ * `refreshViews` is a no-op for old archetypes.
+ */
+export declare function growableSabAllocator(maxBytes?: number): InPlaceBufferAllocator;
+/**
+ * Allocator that backs the store by a single growable **plain `ArrayBuffer`**
+ * (created with `{ maxByteLength: maxBytes }`, grown via `.resize()`). 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
+ * only). Otherwise identical to `growableSabAllocator`:
+ *
+ *   - `isInPlace: true`. A resizable `ArrayBuffer`'s `.resize()` keeps the
+ *     same buffer object and preserves existing TypedArray/DataView views, so
+ *     the store's `extend`/`grow` fast path carries column views forward
+ *     unchanged — exactly as `SharedArrayBuffer.prototype.grow` does. ADR-0008's
+ *     entity-index-hoist-across-grow invariant holds identically.
+ *   - same 256 MiB default cap with hard-ceiling semantics (#380): reaching it
+ *     signals runaway growth upstream, 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
+ * column bytes is backing-agnostic.
+ */
+export declare function heapArraybufferAllocator(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
+ * 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
+ * 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
+ * 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
+ * empirically against Bun + V8): the SAB layer's fast path can carry
+ * forward existing column views across an `extend` without paying for
+ * snapshot+restore. Old DataViews' `byteLength` is frozen at the
+ * pre-grow size, so callers needing to write past that boundary must
+ * 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
+ * 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
+ * core wasm instruction's `-1`, and both are normalised into that error. The
+ * caller should construct memory with a `maximum` large enough for the
+ * workload's worst-case capacity.
+ */
+export declare function wasmMemoryAllocator(memory: WebAssembly.Memory): InPlaceBufferAllocator;
+//# sourceMappingURL=allocator.d.ts.map

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

@@ -0,0 +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;;;;;;mEAM+D;IAC/D,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;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;AA+DF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,GAAE,MAA0B,GAAG,sBAAsB,CA6BjG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CACvC,QAAQ,GAAE,MAA0B,GAClC,sBAAsB,CAuBxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,GAAG,sBAAsB,CA6DtF"}

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

@@ -0,0 +1,69 @@
+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. */
+export declare class StoreColumnOverflowError extends Error {
+    readonly capacity: number;
+    readonly requested: number;
+    constructor(capacity: number, requested: number);
+}
+export declare class BufferBackedColumn<T extends AnyTypedArray> implements ColumnBacking<T> {
+    private _buf;
+    private _capacity;
+    private _len;
+    /** `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 —
+     * 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`.
+     *
+     * 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. */
+    refreshView(newView: T): void;
+    get length(): number;
+    get capacity(): number;
+    push(value: number): void;
+    pop(): number;
+    get(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`. */
+    swapRemove(i: number): number;
+    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
+     * 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). */
+    setLength(len: number): void;
+    /** 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.) */
+    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;
+    /** Append `count` elements from `src[srcOffset..srcOffset+count]`.
+     * Throws on overrun. */
+    bulkAppend(src: T, srcOffset: number, count: number): void;
+    /** Append `count` zeroes. Throws on overrun. */
+    bulkAppendZeroes(count: number): void;
+    /** Append `count` copies of `value`. Throws on overrun. Single-pass
+     * analogue of `bulkAppendZeroes` for a non-zero default. */
+    bulkAppendValue(value: number, count: number): void;
+}
+//# sourceMappingURL=buffer_backed_column.d.ts.map

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

@@ -0,0 +1,69 @@
+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. */
+export declare class StoreColumnOverflowError extends Error {
+    readonly capacity: number;
+    readonly requested: number;
+    constructor(capacity: number, requested: number);
+}
+export declare class BufferBackedColumn<T extends AnyTypedArray> implements ColumnBacking<T> {
+    private _buf;
+    private _capacity;
+    private _len;
+    /** `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 —
+     * 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`.
+     *
+     * 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. */
+    refreshView(newView: T): void;
+    get length(): number;
+    get capacity(): number;
+    push(value: number): void;
+    pop(): number;
+    get(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`. */
+    swapRemove(i: number): number;
+    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
+     * 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). */
+    setLength(len: number): void;
+    /** 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.) */
+    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;
+    /** Append `count` elements from `src[srcOffset..srcOffset+count]`.
+     * Throws on overrun. */
+    bulkAppend(src: T, srcOffset: number, count: number): void;
+    /** Append `count` zeroes. Throws on overrun. */
+    bulkAppendZeroes(count: number): void;
+    /** Append `count` copies of `value`. Throws on overrun. Single-pass
+     * analogue of `bulkAppendZeroes` for a non-zero default. */
+    bulkAppendValue(value: number, count: number): void;
+}
+//# sourceMappingURL=buffer_backed_column.d.ts.map

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

@@ -0,0 +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"}