@oasys/oecs 0.3.1 → 0.4.0

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

@@ -0,0 +1,136 @@
+/**
+ * Action ring — main-thread producer / worker-thread consumer SPSC ring
+ * for client input intents (`send_action`-shaped bytes). Plan §6.5 task
+ * 3 / `docs/ideas/buffer-wasm-sim-plan-2026-05-14T1600.md`.
+ *
+ * Same on-the-wire shape as `command_ring.ts`, but with two practical
+ * differences:
+ *
+ *   1. Producer/consumer roles flip — the action ring is main → worker,
+ *      whereas the command ring is sim → host.
+ *   2. Slot payload carries a `length` prefix because client actions are
+ *      variable-width (the encoded bytes that would normally go straight
+ *      to the WebSocket). `payload[0]` is the length in bytes; bytes
+ *      `[1..1+length)` are the action payload itself.
+ *
+ * Layout (identical to command ring header):
+ *
+ *   [ write_head:   u32 ]   monotonic; modulo `capacity_slots` for slot
+ *   [ read_head:    u32 ]   monotonic
+ *   [ capacity:     u32 ]   slot count, power-of-two
+ *   [ overflow:     u32 ]   0 = OK; 1 = ring exhausted (producer side)
+ *   [ slot 0:       16 B ]  length: u8, payload: [15]u8
+ *   [ slot 1:       16 B ]  ...
+ *
+ * SPSC contract:
+ *   - Producer: main thread, from `GameNetworkClient.send_action`. Pushes
+ *     one entry per user action; `Atomics.store`s `write_head` after each.
+ *   - Consumer: sim worker, drained on each `apply_diff` / `apply_snapshot`
+ *     boundary. `Atomics.store`s `read_head` after each pop.
+ *   - Today's consumer is a no-op observer (logs / counts in DEV) — the
+ *     wire path still goes main → WebSocket → server. PR 5N migrates the
+ *     `PredictionReconciler` into the worker so the action ring becomes
+ *     load-bearing for client-side prediction.
+ *
+ * Overflow:
+ *   - If main writes a slot when `(write_head - read_head) === capacity`,
+ *     it sets `overflow = 1` and the push returns `false`. The server
+ *     send path is independent (`_transport.send(...)` ran first), so an
+ *     overflow doesn't drop the action — it only drops worker
+ *     observability for that one entry.
+ *
+ * Atomics: the head fields (`write_head` / `read_head`) are the
+ * cross-thread synchronization edge — the producer runs on the main
+ * thread, the consumer in the sim worker, and both alias the same
+ * `SharedArrayBuffer`. The producer writes the slot bytes, then
+ * `Atomics.store`s `write_head`; the consumer `Atomics.load`s
+ * `write_head` before touching the slot, reads it, then `Atomics.store`s
+ * `read_head`. These SeqCst ops establish the happens-before that a
+ * plain `DataView` write does not under the JS memory model (#374):
+ * without them the worker could observe a bumped `write_head` before the
+ * producer's `setUint8(len)` + payload `set()` are visible and read a
+ * torn/stale slot, and the producer could read a stale `read_head`
+ * (false overflow, or overwrite a slot mid-read). Slot payload bytes
+ * stay on plain `DataView` / `Uint8Array` ops — the head Atomics fence
+ * them, so no per-byte atomic is needed. A future PR may still add an
+ * `Atomics.wait/notify` pair so the worker can block between actions
+ * instead of polling — additive change, no layout shift.
+ */
+/** Total bytes for the ring header. Identical to `command_ring`. */
+export declare const ACTION_RING_HEADER_BYTES = 16;
+/** Fixed slot size — 1-byte length + 15-byte payload. */
+export declare const ACTION_RING_SLOT_BYTES = 16;
+/** Default ring capacity in slots. Sized for ~250 ms of click-spam at 60
+ * Hz on the high end of human input rates; 256 × 16 B = 4 KiB + 16 B
+ * header. */
+export declare const ACTION_RING_DEFAULT_CAPACITY_SLOTS = 256;
+/** Max payload bytes per slot (slot size minus the length prefix). All
+ * actions defined in `packages/protocol/src/actions.ts` encode to under
+ * 8 bytes, so this is comfortably above today's max. */
+export declare const ACTION_RING_MAX_PAYLOAD_BYTES: number;
+/** Byte offsets within the ring header. Matches `command_ring` so a
+ * future shared helper can normalise across both rings without per-ring
+ * arithmetic. */
+export declare const ACTION_RING_HEADER_OFFSETS: {
+    readonly write_head: 0;
+    readonly read_head: 4;
+    readonly capacity_slots: 8;
+    readonly overflow_flag: 12;
+};
+/** Total bytes the ring occupies for `capacity_slots` slots. */
+export declare function actionRingBytes(capacitySlots: number): number;
+export declare class ActionRingError extends Error {
+    constructor(message: string);
+}
+/** Initialise the ring header at `ringOff` in the SAB. Zeroes heads
+ * and the overflow flag; sets `capacity_slots`. Slot bytes are left
+ * as-is (callers normally allocate the ring on a zero-initialised SAB). */
+export declare function initActionRing(view: DataView, ringOff: number, capacitySlots: number): void;
+/** Read live ring-header fields. Heads are stored signed but returned
+ * unsigned (`>>> 0`) so the monotonic-counter arithmetic below is
+ * identical to the prior `getUint32` behaviour. */
+export declare function actionRingWriteHead(view: DataView, ringOff: number): number;
+export declare function actionRingReadHead(view: DataView, ringOff: number): number;
+export declare function actionRingCapacitySlots(view: DataView, ringOff: number): number;
+export declare function actionRingOverflow(view: DataView, ringOff: number): boolean;
+/** Pending entry count = `(write_head - read_head) mod 2^32`. */
+export declare function pendingActionCount(view: DataView, ringOff: number): number;
+/** Push an action into the ring. `payload` must be in
+ * `[1, ACTION_RING_MAX_PAYLOAD_BYTES]`; longer payloads — and **empty**
+ * ones — are an `ActionRingError` (the producer is the only caller and it
+ * can size its inputs ahead of time). The zero-length rejection closes the
+ * lower-bound footgun: a 0-byte slot is indistinguishable from
+ * `popAction`'s empty-ring sentinel (`0`), so admitting one would let it
+ * masquerade as "ring empty". No encoder produces a 0-byte payload, so this
+ * only ever rejects the ABI-skew bug case (#430). Returns `false` on
+ * overflow and sets the overflow flag. */
+export declare function pushAction(view: DataView, ringOff: number, payload: Uint8Array): boolean;
+/** Pop one action from the ring. Returns the byte length written into
+ * `outPayload`, or `0` if the ring was empty. `outPayload` must be at
+ * least `ACTION_RING_MAX_PAYLOAD_BYTES`; only the first `length` bytes
+ * are meaningful after a non-zero return.
+ *
+ * NOTE: a `0` return is ambiguous — it means "ring empty" OR "a 0-byte
+ * slot" (the latter only reachable via ABI-skew, since `pushAction`
+ * rejects empty payloads). Callers that loop must decide emptiness from
+ * the heads (`pendingActionCount` / `write_head === read_head`), not
+ * from this return value; see `drainActionRing` and #430. */
+export declare function popAction(view: DataView, ringOff: number, outPayload: Uint8Array): number;
+/** Drain every pending action, invoking `handler(payload)` per entry.
+ * The `payload` passed to the handler is a freshly-copied
+ * `Uint8Array(length)` so handlers can hold it past the next pop without
+ * aliasing the scratch buffer. Returns the number of actions drained.
+ *
+ * Termination is decided from the heads (`pendingActionCount`), NOT from
+ * `popAction`'s return value. A genuine 0-byte slot returns `0` — the same
+ * value `popAction` yields on an empty ring — so terminating on `len === 0`
+ * would silently consume the zero-length entry and strand everything queued
+ * behind it for a tick (#430). The heads check is SPSC-safe: this consumer
+ * is the sole reader, so a non-zero pending count cannot race to empty before
+ * the `popAction` below. */
+export declare function drainActionRing(view: DataView, ringOff: number, handler: (payload: Uint8Array) => void): number;
+/** Clear the overflow flag. The producer sets it on a failed push; the
+ * consumer can reset it once it has observed and logged the condition,
+ * so a single overflow doesn't keep firing dev assertions. */
+export declare function clearActionRingOverflow(view: DataView, ringOff: number): void;
+//# sourceMappingURL=action_ring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"action_ring.d.ts","sourceRoot":"","sources":["../../../src/core/store/action_ring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,yDAAyD;AACzD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;aAEa;AACb,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD;;wDAEwD;AACxD,eAAO,MAAM,6BAA6B,QAA6B,CAAC;AAExE;;iBAEiB;AACjB,eAAO,MAAM,0BAA0B;;;;;CAK7B,CAAC;AAwBX,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE7D;AAMD,qBAAa,eAAgB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI3B;AAED;;2EAE2E;AAC3E,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAiB3F;AAED;;mDAEmD;AACnD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3E;AACD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1E;AACD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/E;AACD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3E;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;;;;0CAQ0C;AAC1C,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAoCxF;AAED;;;;;;;;;6DAS6D;AAC7D,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAwBzF;AAED;;;;;;;;;;;4BAW4B;AAC5B,wBAAgB,eAAe,CAC9B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,GACpC,MAAM,CAUR;AAED;;8DAE8D;AAC9D,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7E"}

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;AAKF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,GAAE,MAA0B,GAAG,sBAAsB,CAsDjG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CACvC,QAAQ,GAAE,MAA0B,GAClC,sBAAsB,CAwCxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,GAAG,sBAAsB,CA6DtF"}

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

@@ -0,0 +1,69 @@
+import { ColumnBacking } from '../../type_primitives';
+import { AnyTypedArray } from './column_store';
+/** 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"}