@oasys/oecs 0.3.0 → 0.4.0

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

@@ -0,0 +1,95 @@
+/**
+ * Event ring — SPSC ring buffer for ECS signal/event payloads shared
+ * between TS and the Zig sim. (#247 / Phase 4 PR 4C)
+ *
+ * Same byte layout as the command ring (`command_ring.ts`); the two
+ * could share a primitive but keeping them separate makes the
+ * direction of flow explicit: command ring is WASM→TS (structural
+ * intents to drain post-tick); event ring is bidirectional during
+ * `tick()` — Zig systems push events, TS readers (or other Zig
+ * systems) drain.
+ *
+ * Layout (identical to command ring):
+ *
+ *   [ write_head:    u32 ]   slot 0..N-1, monotonic (NOT slot-modulo)
+ *   [ read_head:     u32 ]   slot 0..N-1, monotonic
+ *   [ capacity:      u32 ]   slot count, power-of-two
+ *   [ overflow_flag: u32 ]   0 = OK; 1 = sticky overflow witness
+ *   [ slot 0:        16 B ]  opCode: u8, payload: [15]u8
+ *   [ slot 1:        16 B ]  ...
+ *
+ * Op codes: event-def IDs (assigned by `ECS.registerEvent()` at
+ * registration time; #247 plan §required-FFI). The 0 op-code is
+ * reserved as the empty-slot marker so a zero-initialised SAB does not
+ * appear to hold a valid event. Event-def registration starts numbering
+ * from 1 to honour this; the engine integration in 4D+ enforces it.
+ *
+ * SPSC contract (Phase 4 scope, single host thread):
+ *   - Producer: Zig sim `tick()` (post-4D) OR TS host (test producers /
+ *     existing JS-side emitters bridged into the ring).
+ *   - Consumer: TS host drain (post-4D) OR Zig system that reads
+ *     queued events from a sibling system.
+ *   - The two never run concurrently in Phase 4 (single host thread
+ *     orchestrates both). Phase 5's worker offload promotes the head
+ *     bumps to `Atomics.store`; that's an additive change without
+ *     altering the layout.
+ *
+ * Payload size: fixed 15 bytes per slot. Today's events all fit
+ * (e.g. a 12-byte 3-field event, a 4-byte 1-field event, a 0-field
+ * signal). Larger payloads require a separate variable-size ring
+ * design — out of scope here.
+ *
+ * Region placement: between the entity-index region and the descriptor
+ * region so its offset is stable across descriptor / column growth.
+ * `header.event_ring_off` (the field promoted out of `_reserved0` in
+ * #245's reservation) carries the offset; 0 means absent.
+ */
+/** Total bytes for the ring header. Matches command ring exactly. */
+export declare const EVENT_RING_HEADER_BYTES = 16;
+/** Fixed slot size — 1-byte opCode + 15-byte payload. Matches
+ * command ring exactly. */
+export declare const EVENT_RING_SLOT_BYTES = 16;
+/** Default ring capacity in slots. 256 × 16 B = 4 KiB of slot data
+ * plus 16 B header. Mirrors `COMMAND_RING_DEFAULT_CAPACITY_SLOTS`. */
+export declare const EVENT_RING_DEFAULT_CAPACITY_SLOTS = 256;
+/** Byte offsets within the ring header. Mirrored on the Zig side in
+ * `packages/sim/src/event_ring.zig` — keep in sync. */
+export declare const EVENT_RING_HEADER_OFFSETS: {
+    readonly write_head: 0;
+    readonly read_head: 4;
+    readonly capacity_slots: 8;
+    readonly overflow_flag: 12;
+};
+/** Op-code = `0` is reserved across the SAB layer as "empty slot"
+ * (see file header). Event-def IDs start at 1; `ECS.registerEvent`
+ * shifts to honour this when wiring SAB-backed channels in 4D+. */
+export declare const EVENT_OP_EMPTY = 0;
+/** Total bytes the ring occupies for `capacity_slots` slots. */
+export declare function eventRingBytes(capacitySlots: number): number;
+export declare class EventRingError extends Error {
+    constructor(message: string);
+}
+/** Initialise the ring header at `ringOff` in the SAB. Zeroes
+ * `write_head`, `read_head`, and `overflow_flag`; sets `capacity_slots`.
+ * Slot bytes are left as-is (callers normally allocate the ring on a
+ * fresh, zero-initialised SAB). */
+export declare function initEventRing(view: DataView, ringOff: number, capacitySlots: number): void;
+export declare function ringWriteHead(view: DataView, ringOff: number): number;
+export declare function ringReadHead(view: DataView, ringOff: number): number;
+export declare function ringCapacitySlots(view: DataView, ringOff: number): number;
+export declare function ringOverflow(view: DataView, ringOff: number): boolean;
+/** Pending event count = `(write_head - read_head) mod 2^32`. */
+export declare function pendingEventCount(view: DataView, ringOff: number): number;
+/** Push an event into the ring. Returns `false` on overflow and sets
+ * the (sticky) overflow flag. `opCode` must be > 0 — 0 is reserved as
+ * the empty-slot marker. Payload must be exactly 15 bytes. */
+export declare function pushEvent(view: DataView, ringOff: number, opCode: number, payload: Uint8Array): boolean;
+/** Read one event from the ring. Returns opCode (0 = empty/no event)
+ * and fills `outPayload` with 15 bytes. When 0 is returned,
+ * `outPayload` is untouched. */
+export declare function popEvent(view: DataView, ringOff: number, outPayload: Uint8Array): number;
+/** Drain every pending event, calling `handler` for each. Yields a
+ * freshly-copied 15-byte Uint8Array per event so handlers can hold the
+ * payload past the next iteration. Returns the count drained. */
+export declare function drainEventRing(view: DataView, ringOff: number, handler: (opCode: number, payload: Uint8Array) => void): number;
+//# sourceMappingURL=event_ring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event_ring.d.ts","sourceRoot":"","sources":["../../../src/core/store/event_ring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;2BAC2B;AAC3B,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;sEACsE;AACtE,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAErD;uDACuD;AACvD,eAAO,MAAM,yBAAyB;;;;;CAK5B,CAAC;AAEX;;mEAEmE;AACnE,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE5D;AAMD,qBAAa,cAAe,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI3B;AAED;;;mCAGmC;AACnC,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAU1F;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAErE;AACD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpE;AACD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE;AACD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAErE;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED;;8DAE8D;AAC9D,wBAAgB,SAAS,CACxB,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,UAAU,GACjB,OAAO,CA4BT;AAED;;gCAEgC;AAChC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAiBxF;AAED;;iEAEiE;AACjE,wBAAgB,cAAc,CAC7B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,KAAK,IAAI,GACpD,MAAM,CASR"}

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

@@ -0,0 +1,109 @@
+import { ArchetypeGrowSpec } from './grow';
+import { ArchetypeSpec, CreateColumnStoreOptions, ColumnStore } from './column_store';
+import { BufferAllocator } from './allocator';
+import { StoreRegionOffsetField } from './store_regions';
+/**
+ * Derive `CreateColumnStoreOptions` from an old ColumnStore so a slow-path realloc
+ * preserves the same set of optional regions at the same byte offsets in the
+ * new SAB. Without this, an extend / grow would silently drop a region — the
+ * command ring's pending commands, every entity placement in the index, etc.
+ * would be lost.
+ *
+ * Walks `STORE_PREFIX_REGIONS`: each present region's `readOptions` replays the
+ * exact capacity the engine configured (regions may carry non-default sizes),
+ * not just the default. Live state (write_head, length, …) is preserved
+ * separately via `snapshotPrefixRegions`.
+ *
+ * Also re-applies the descriptor-region headroom policy
+ * (`reservedDescriptorBytes`, #541). Unlike the prefix regions this is NOT
+ * read from the SAB bytes — it's a JS-side policy carried on
+ * `ColumnStoreInternal._reservedDescriptorBytes` — but it belongs here for the
+ * same reason: without it the realloc'd store drops to zero descriptor
+ * headroom and every later `extendColumnStore` takes the slow path forever.
+ * Re-reserving the same margin (additive, see `planLayout`) keeps the #237
+ * in-place fast path alive across reallocs.
+ */
+export declare function optionsFromOld(old: ColumnStore): CreateColumnStoreOptions;
+/** A prefix-region snapshot: the live bytes of every present region from the
+ * old SAB. `mechanism` is keyed by the `StoreHeader` field holding a mechanism
+ * region's offset; `consumer` is keyed by `region_id` (consumer regions have no
+ * named header field). Pairs `snapshotPrefixRegions` with
+ * `restorePrefixRegions`. */
+export interface PrefixRegionSnapshot {
+    readonly mechanism: Map<StoreRegionOffsetField, Uint8Array>;
+    readonly consumer: Map<number, Uint8Array>;
+}
+/**
+ * Snapshot the live bytes of every present region — both engine MECHANISM
+ * regions (STORE_PREFIX_REGIONS) and CONSUMER regions (the region-table
+ * directory) — from the old SAB BEFORE any allocator call that may detach
+ * views. Each entry is a heap `Uint8Array` copy (via `slice()`) so it survives
+ * an allocator-induced detach; `restorePrefixRegions` places it back at the
+ * matching offset in the new SAB.
+ *
+ * Header bytes themselves are NOT snapshotted — `createColumnStore` writes the
+ * header (and the region-table directory) from scratch with the correct
+ * view_stamp (bumped after this call) and offsets.
+ */
+export declare function snapshotPrefixRegions(old: ColumnStore): PrefixRegionSnapshot;
+/** Restore prefix-region byte snapshots into `newStore` at the matching
+ * region offsets. Pairs with `snapshotPrefixRegions`. The new SAB's regions
+ * were sized identically by `optionsFromOld`, so each snapshot lands at the
+ * same length its source had — mechanism regions at their named header offset,
+ * consumer regions at the offset the rebuilt region-table resolves their id to. */
+export declare function restorePrefixRegions(newStore: ColumnStore, snap: PrefixRegionSnapshot): void;
+/**
+ * Snapshot per-archetype live column bytes from `old` BEFORE any
+ * subsequent allocator call may detach the underlying typed-array views.
+ * Returned shape: `{ archetype_id → Uint8Array[] }`, one entry per
+ * column in `columnsInOrder`. Each `Uint8Array` is a fresh copy
+ * (not a view) so it survives a `WebAssembly.Memory.grow`. Archetypes
+ * with `row_count === 0` are omitted — nothing to copy.
+ *
+ * Shared with `growColumnStore`; both functions need the same
+ * snapshot-before-allocate pattern under the wasm-memory allocator.
+ */
+export declare function snapshotLiveColumns(old: ColumnStore, rowCountsById: Map<number, number>): Map<number, Uint8Array[]>;
+/**
+ * Write per-archetype column snapshots produced by `snapshotLiveColumns`
+ * into `newStore`'s column views. The snapshot's column ORDER must match
+ * the new archetype's `columnsInOrder` (extend / grow guarantee this
+ * because they carry the column spec forward unchanged).
+ */
+export declare function restoreColumnSnapshots(newStore: ColumnStore, snapshots: Map<number, Uint8Array[]>): void;
+export interface ExtendPlan {
+    /** Archetypes to append. Each `archetype_id` MUST be absent from
+     * `old.archetypes`; collisions throw `StoreExtendError`. */
+    readonly newArchetypes: readonly ArchetypeSpec[];
+    /** Per-existing-archetype live row counts. Same shape as
+     * `GrowPlan.archetypes` so callers can reuse plan-building helpers.
+     * Omitted or `0` ⇒ no rows to copy (the archetype is empty). */
+    readonly existing?: readonly ArchetypeGrowSpec[];
+}
+export interface ExtendResult {
+    readonly store: ColumnStore;
+    readonly oldViewStamp: number;
+    readonly newViewStamp: number;
+    /** True when the in-place fast path (#237 Option A) was taken: the SAB
+     * instance is reused, existing column TypedArray views are unchanged,
+     * and callers may skip `refreshViews` on every pre-existing
+     * Archetype. False when the slow path ran (fresh SAB or wasm-memory
+     * grow with detached views); callers MUST refresh every Archetype's
+     * SAB-backed columns from the returned `store` before reading them. */
+    readonly viewsPreserved: boolean;
+}
+export declare class StoreExtendError extends Error {
+    constructor(message: string);
+}
+/** Allocate a new SAB sized for `old` + `plan.newArchetypes`, copy
+ * existing rows, bump `view_stamp`.
+ *
+ * `allocator` (PR 3D / #234): pluggable buffer source forwarded into
+ * `createColumnStore`. When the allocator is `wasmMemoryAllocator`,
+ * `memory.grow` may detach `old`'s typed-array views before the copy
+ * runs — so live rows are snapshotted into heap `Uint8Array`s BEFORE the
+ * allocator call and restored into the new views afterwards. The cost
+ * is one extra heap allocation per live archetype-column; negligible
+ * compared to the SAB walk itself. */
+export declare function extendColumnStore(old: ColumnStore, plan: ExtendPlan, allocator?: BufferAllocator): ExtendResult;
+//# sourceMappingURL=extend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extend.d.ts","sourceRoot":"","sources":["../../../src/core/store/extend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAEhD,OAAO,EAMN,KAAK,aAAa,EAElB,KAAK,wBAAwB,EAC7B,KAAK,WAAW,EAEhB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAQnD,OAAO,EAGN,KAAK,sBAAsB,EAC3B,MAAM,iBAAiB,CAAC;AAGzB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,wBAAwB,CAyCzE;AAED;;;;6BAI6B;AAC7B,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,sBAAsB,EAAE,UAAU,CAAC,CAAC;IAC5D,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,oBAAoB,CAsB5E;AAED;;;;mFAImF;AACnF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAc5F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAClC,GAAG,EAAE,WAAW,EAChB,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAmB3B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACrC,QAAQ,EAAE,WAAW,EACrB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,GAClC,IAAI,CAeN;AAED,MAAM,WAAW,UAAU;IAC1B;gEAC4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,SAAS,aAAa,EAAE,CAAC;IACjD;;oEAEgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;2EAKuE;IACvE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CACjC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI3B;AAED;;;;;;;;;sCASsC;AACtC,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE,eAAe,GACzB,YAAY,CAoLd"}

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

@@ -0,0 +1,39 @@
+import { ColumnStore } from './column_store';
+import { BufferAllocator } from './allocator';
+/** Per-archetype growth input. The caller picks the new `row_capacity` and
+ * declares the current live `row_count` so we know how many rows to copy. */
+export interface ArchetypeGrowSpec {
+    readonly archetypeId: number;
+    readonly newRowCapacity: number;
+    readonly rowCount: number;
+}
+export interface GrowPlan {
+    readonly archetypes: readonly ArchetypeGrowSpec[];
+}
+/** Returned alongside the new `ColumnStore` so callers can sanity-check the
+ * grow (and so tests can assert it without re-reading the SAB). */
+export interface GrowResult {
+    readonly store: ColumnStore;
+    readonly oldViewStamp: number;
+    readonly newViewStamp: number;
+    /** True when the in-place fast path ran: every archetype EXCEPT those in
+     * `grownArchetypeIds` kept its column views, so the caller only needs to
+     * `refreshViews` the grown ones. False on the realloc path, where the
+     * whole store moved and every view must be refreshed. */
+    readonly viewsPreserved: boolean;
+    /** Archetype ids whose columns were relocated (in-place path). Empty on
+     * the realloc path. */
+    readonly grownArchetypeIds: readonly number[];
+}
+export declare class StoreGrowError extends Error {
+    constructor(message: string);
+}
+/** Allocate a new SAB sized for `plan`, copy live rows from `old`, bump
+ * `view_stamp`. With the default allocator the old SAB is untouched and
+ * callers may continue reading from it until they finish swapping in
+ * the new views. With a `wasmMemoryAllocator`, `old`'s typed-array
+ * views may be detached as soon as `createColumnStore` returns — live
+ * data is snapshotted before the allocator call to make both code paths
+ * behave identically from the caller's perspective. (PR 3D / #234) */
+export declare function growColumnStore(old: ColumnStore, plan: GrowPlan, allocator?: BufferAllocator): GrowResult;
+//# sourceMappingURL=grow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grow.d.ts","sourceRoot":"","sources":["../../../src/core/store/grow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAUH,OAAO,EAQN,KAAK,WAAW,EAEhB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AASnD;6EAC6E;AAC7E,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAClD;AAED;mEACmE;AACnE,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;6DAGyD;IACzD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;2BACuB;IACvB,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AA4KD,qBAAa,cAAe,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI3B;AAED;;;;;;sEAMsE;AACtE,wBAAgB,eAAe,CAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,QAAQ,EACd,SAAS,CAAC,EAAE,eAAe,GACzB,UAAU,CAgIZ"}

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

@@ -0,0 +1,64 @@
+import { STORE_MAGIC, SIM_ABI_VERSION, STORE_HEADER_BYTES, STORE_HEADER_OFFSETS, REGION_TABLE_ENTRY_BYTES, REGION_TABLE_ENTRY_OFFSETS } from './__generated__/abi';
+export { STORE_MAGIC, SIM_ABI_VERSION, STORE_HEADER_BYTES, STORE_HEADER_OFFSETS, REGION_TABLE_ENTRY_BYTES, REGION_TABLE_ENTRY_OFFSETS };
+export interface StoreHeader {
+    /** Magic value `STORE_MAGIC`; used to detect a stale or foreign buffer
+     * before any other field is trusted. */
+    readonly magic: number;
+    /** ABI version; mismatch means the WASM and TS disagree on layout and
+     * the SAB must not be used. */
+    readonly simAbiVersion: number;
+    /** Monotonic; incremented every time the host reallocates the SAB.
+     * Cached TypedArray views become stale on bump. (#171 §8.1) */
+    readonly viewStamp: number;
+    /** Total SAB size in bytes. */
+    readonly capacity: number;
+    /** Number of archetype regions described by the layout descriptor. */
+    readonly archetypeCount: number;
+    /** Byte offset into the SAB where the layout descriptor region starts. */
+    readonly layoutDescriptorOff: number;
+    /** Byte offset of the WASM→TS command ring header. (#171 §7.5) */
+    readonly commandRingOff: number;
+    /** Byte offset of the TS→WASM action ring header. (#171 §7.5, Phase 5) */
+    readonly actionRingOff: number;
+    /** Byte offset of the entity-index region (entityId → archetype_id,
+     * row, generation lookup). 0 means absent — fixtures and bare-SAB
+     * tests that don't need the index see the v1 layout (the engine's
+     * `Store` always allocates one). (#245 / Phase 4 PR 4B) */
+    readonly entityIndexOff: number;
+    /** Byte offset of the event ring region (ECS signal payloads shared
+     * with the Zig sim). 0 means absent. (#247 / Phase 4 PR 4C) */
+    readonly eventRingOff: number;
+    /** Byte offset of the region-table directory — a `RegionTableEntry[]`
+     * (`(region_id, byte_offset, byte_length)` triples) holding one entry
+     * per consumer-declared region. 0 means no consumer regions were
+     * declared. The engine treats `region_id` as opaque; a consumer resolves
+     * its region with `findRegionOffset(view, header, id)` (TS) /
+     * `abi.find_region(header_addr, id)` (Zig). Replaces the five game-named
+     * offset fields (`terrain_off`/`spatial_grid_off`/… ) the SAB header
+     * used to hard-code. (#623 — de-game the SAB substrate; ADR-0018.) */
+    readonly regionTableOff: number;
+    /** Number of `RegionTableEntry` records at `region_table_off`. (#623) */
+    readonly regionTableCount: number;
+    /** Byte offset of the sim-bindings region — an opaque block of `u16`
+     * `(component_id, field_id)` IDs (layout owned by the game, in
+     * `@internal/sim`'s `sim_bindings.ts` / `bindings.zig`). The host writes it
+     * once per layout via `write_sim_bindings`; the Zig per-system exports
+     * (`tick_cooldown_ready` / `tick_movement_tick` / `tick_faith_production`
+     * and the batched `tick_all`) read their IDs from here instead of taking
+     * them as call args. Present only when the consumer opts into a WASM backend
+     * by passing `bindingsRegionBytes` to `createColumnStore`; 0 = absent (a
+     * pure-TS game pays nothing for this region). The size is a runtime input,
+     * not an engine ABI constant, since #625. (v5 / "SAB-is-the-interface".) */
+    readonly bindingsOff: number;
+}
+export declare function writeStoreHeader(view: DataView, h: StoreHeader): void;
+export declare function readStoreHeader(view: DataView): StoreHeader;
+/** Increment `view_stamp` in place after a host-side SAB reallocation. The
+ * monotonic counter is the trigger for cached-view invalidation on the TS
+ * side and for re-pointing in WASM. (#171 §8.1) */
+export declare function bumpViewStamp(view: DataView): number;
+/** True iff the buffer's first four bytes are `STORE_MAGIC` AND the ABI
+ * version matches the current build. Used by both TS and WASM as a
+ * pre-flight before treating any other field as meaningful. */
+export declare function isValidSab(view: DataView): boolean;
+//# sourceMappingURL=header.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../../src/core/store/header.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAoBH,OAAO,EACN,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,0BAA0B,EAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACN,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,0BAA0B,EAC1B,CAAC;AAEF,MAAM,WAAW,WAAW;IAC3B;4CACwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;mCAC+B;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;mEAC+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,kEAAkE;IAClE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;+DAG2D;IAC3D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;mEAC+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;;;0EAOsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;;;;;gFAS4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,GAAG,IAAI,CAcrE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,WAAW,CAgB3D;AAED;;mDAEmD;AACnD,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAIpD;AAED;;+DAE+D;AAC/D,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAKlD"}

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

@@ -0,0 +1,16 @@
+export { STORE_MAGIC, SIM_ABI_VERSION, STORE_HEADER_BYTES, STORE_HEADER_OFFSETS, REGION_TABLE_ENTRY_BYTES, REGION_TABLE_ENTRY_OFFSETS, type StoreHeader, writeStoreHeader, readStoreHeader, bumpViewStamp, isValidSab } from './header';
+export { type StoreRegionSpec, type RegionTableEntry, type ColumnStoreRegionHandle, RegionRegistryError, regionTableBytes, validateRegionSpecs, writeRegionTableEntry, readRegionTableEntry, writeRegionTable, readRegionTable, readHeaderRegionTable, findRegionOffset, findRegionEntry } from './region_table';
+export { TYPE_TAG, type TypeTagValue, TYPE_TAG_STRIDE, TYPED_ARRAY_TAG_TO_TYPE_TAG, COLUMN_DESCRIPTOR_BYTES, COLUMN_DESCRIPTOR_OFFSETS, type ColumnDescriptor, writeColumnDescriptor, readColumnDescriptor, ARCHETYPE_DESCRIPTOR_HEADER_BYTES, ARCHETYPE_DESCRIPTOR_OFFSETS, COMPONENT_MASK_WORDS, STORE_DESCRIPTOR_COMPONENT_LIMIT, type ArchetypeDescriptor, archetypeDescriptorBytes, writeArchetypeDescriptor, readArchetypeDescriptor, writeLayoutDescriptorRegion, readLayoutDescriptorRegion, layoutDescriptorRegionBytes } from './descriptor';
+export { type ColumnSpec, type ArchetypeSpec, type ColumnView, type ArchetypeViews, type ColumnStore, type AnyTypedArray, type CreateColumnStoreOptions, alignUp, buildArchetypeViews, columnKey, createColumnStore, StoreLayoutOverflowError, STORE_MAX_BYTE_OFFSET, COMMAND_RING_DEFAULT_CAPACITY_SLOTS, ENTITY_INDEX_DEFAULT_CAPACITY, EVENT_RING_DEFAULT_CAPACITY_SLOTS } from './column_store';
+export { EVENT_OP_EMPTY, EVENT_RING_HEADER_BYTES, EVENT_RING_SLOT_BYTES, EVENT_RING_HEADER_OFFSETS, EventRingError, drainEventRing, eventRingBytes, initEventRing, pendingEventCount, popEvent, pushEvent, ringCapacitySlots as eventRingCapacitySlots, ringOverflow as eventRingOverflow, ringReadHead as eventRingReadHead, ringWriteHead as eventRingWriteHead } from './event_ring';
+export { ENTITY_INDEX_HEADER_BYTES, ENTITY_INDEX_BYTES_PER_SLOT, ENTITY_INDEX_HEADER_OFFSETS, EntityIndexError, buildEntityIndexViews, entityIndexCapacity, entityIndexLength, entityIndexRegionBytes, initEntityIndexRegion, setEntityIndexLength } from './entity_index';
+export { COMMAND_OP_EMPTY, COMMAND_RING_HEADER_BYTES, COMMAND_RING_SLOT_BYTES, COMMAND_RING_HEADER_OFFSETS, CommandRingError, commandRingBytes, drainCommandRing, initCommandRing, pendingCommandCount, popCommand, pushCommand, ringCapacitySlots, ringOverflow, ringReadHead, ringWriteHead } from './command_ring';
+export { type PayloadCodec, CommandDispatcher } from './command_dispatch';
+export { BufferBackedColumn, StoreColumnOverflowError } from './buffer_backed_column';
+export { type ArchetypeGrowSpec, type GrowPlan, type GrowResult, StoreGrowError, growColumnStore } from './grow';
+export { type ExtendPlan, type ExtendResult, StoreExtendError, extendColumnStore, snapshotLiveColumns, restoreColumnSnapshots } from './extend';
+export { type BufferAllocator, type InPlaceBufferAllocator, StoreCapExceededError, SabUnavailableError, DEFAULT_SAB_ALLOCATOR, wasmMemoryAllocator, growableSabAllocator, heapArraybufferAllocator } from './allocator';
+export { StoreRestoreError, snapshotColumnStore, restoreColumnStore } from './snapshot';
+export { FNV1A_OFFSET_BASIS, FNV1A_PRIME, fnv1a32, fnv1aStep, fnv1aStepWord, columnStoreStateHash } from './state_hash';
+export { ACTION_RING_DEFAULT_CAPACITY_SLOTS, ACTION_RING_HEADER_BYTES, ACTION_RING_HEADER_OFFSETS, ACTION_RING_MAX_PAYLOAD_BYTES, ACTION_RING_SLOT_BYTES, ActionRingError, actionRingBytes, actionRingCapacitySlots, actionRingOverflow, actionRingReadHead, actionRingWriteHead, clearActionRingOverflow, drainActionRing, initActionRing, pendingActionCount, popAction, pushAction } from './action_ring';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/store/index.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,74 @@
+import { REGION_TABLE_ENTRY_BYTES, REGION_TABLE_ENTRY_OFFSETS } from './__generated__/abi';
+export { REGION_TABLE_ENTRY_BYTES, REGION_TABLE_ENTRY_OFFSETS };
+/** A consumer-declared SAB region. The consumer owns `id` (a nonzero integer,
+ * distinct within its region set, that it also resolves on the read side),
+ * computes `bytes`, and seeds the region header + contents in `init`.
+ *
+ * `init` runs ONCE at first allocation. Across a SAB grow/extend the region's
+ * live bytes are snapshotted and restored verbatim (the table is
+ * self-describing), so `init` is not re-run — a consumer must not rely on it
+ * firing per realloc. */
+export interface StoreRegionSpec {
+    /** Consumer-owned region id (nonzero, distinct). Written to the directory;
+     * resolved by the consumer via `findRegionOffset` / `abi.find_region`. */
+    readonly id: number;
+    /** Human label for diagnostics / the self-documenting directory dump. */
+    readonly name: string;
+    /** Byte size to allocate for this region (consumer computes from its knobs).
+     * Must be > 0. */
+    readonly bytes: number;
+    /** Initialise the region header + seed bytes at absolute byte offset `off`. */
+    readonly init: (view: DataView, off: number) => void;
+}
+/** One decoded directory record. */
+export interface RegionTableEntry {
+    readonly regionId: number;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+}
+/** A resolved handle to a consumer region, returned by `ECS.regionHandle` /
+ * `Store.regionHandle`. Carries the live `buffer`/`view` plus the region's byte
+ * `offset` and full `bytes`, so a consumer's region module can build a
+ * TypedArray view over exactly the region's span without re-reading the
+ * directory. Re-fetch after a SAB grow (the offset/view may have moved). */
+export interface ColumnStoreRegionHandle {
+    /** `ArrayBufferLike` — see `ColumnStore.buffer`. Consumer regions are a SAB-profile
+     * feature (WASM/worker), so in practice this is a `SharedArrayBuffer` wherever
+     * regions are declared; the type is widened only because it flows from the
+     * backing-agnostic store. */
+    readonly buffer: ArrayBufferLike;
+    readonly view: DataView;
+    readonly offset: number;
+    readonly bytes: number;
+}
+export declare class RegionRegistryError extends Error {
+    constructor(message: string);
+}
+/** Bytes a region-table directory of `count` entries occupies. */
+export declare function regionTableBytes(count: number): number;
+/** Validate a consumer region set before layout: ids must be nonzero (0 is the
+ * "absent" sentinel `findRegionOffset` returns) and distinct, and each region
+ * must request a positive byte size. Throws `RegionRegistryError` otherwise —
+ * the same loud-failure stance the mechanism registry's paired-knob guards take. */
+export declare function validateRegionSpecs(regions: readonly StoreRegionSpec[]): void;
+/** Write one directory record at absolute byte offset `off`. */
+export declare function writeRegionTableEntry(view: DataView, off: number, e: RegionTableEntry): void;
+/** Read one directory record at absolute byte offset `off`. */
+export declare function readRegionTableEntry(view: DataView, off: number): RegionTableEntry;
+/** Write the whole directory of `entries` at `tableOff`. */
+export declare function writeRegionTable(view: DataView, tableOff: number, entries: readonly RegionTableEntry[]): void;
+/** Read all `count` directory records starting at `tableOff`, in order. */
+export declare function readRegionTable(view: DataView, tableOff: number, count: number): RegionTableEntry[];
+/** Read the directory described by the SAB header (`region_table_off` /
+ * `region_table_count`). Empty when no consumer regions were declared. */
+export declare function readHeaderRegionTable(view: DataView): RegionTableEntry[];
+/** Resolve a consumer region's byte offset by `region_id`, or 0 when absent
+ * (no directory, or no matching entry). The TS twin of Zig
+ * `abi.find_region(header_addr, region_id)`; 0 is an unambiguous "absent"
+ * sentinel because a real region never starts at SAB byte 0 (the header does). */
+export declare function findRegionOffset(view: DataView, regionId: number): number;
+/** Resolve a consumer region's `(byte_offset, byte_length)` by `region_id`, or
+ * `null` when absent. Use when a reader needs the region's size (e.g. to
+ * materialise a TypedArray view) and not just its start. */
+export declare function findRegionEntry(view: DataView, regionId: number): RegionTableEntry | null;
+//# sourceMappingURL=region_table.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"region_table.d.ts","sourceRoot":"","sources":["../../../src/core/store/region_table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACN,wBAAwB,EACxB,0BAA0B,EAE1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,CAAC;AAEhE;;;;;;;yBAOyB;AACzB,MAAM,WAAW,eAAe;IAC/B;8EAC0E;IAC1E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;sBACkB;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED;;;;4EAI4E;AAC5E,MAAM,WAAW,uBAAuB;IACvC;;;iCAG6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI3B;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAiBD;;;oFAGoF;AACpF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,CAqB7E;AAED,gEAAgE;AAChE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAI5F;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAMlF;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAClC,IAAI,CAIN;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAC9B,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACX,gBAAgB,EAAE,CAMpB;AAED;0EAC0E;AAC1E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,gBAAgB,EAAE,CAKxE;AAED;;;kFAGkF;AAClF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWzE;AAED;;4DAE4D;AAC5D,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CASzF"}

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

@@ -0,0 +1,43 @@
+import { ColumnStore } from './column_store';
+import { BufferAllocator } from './allocator';
+export declare class StoreRestoreError extends Error {
+    constructor(message: string);
+}
+/** Zero-copy `Uint8Array` view over the SAB's used byte range. Length is
+ * `header.capacity` — the canonical size, NOT `buffer.byteLength`. The two
+ * coincide for `DEFAULT_SAB_ALLOCATOR` (it allocates exactly `totalBytes`),
+ * but `wasmMemoryAllocator` / `growableSabAllocator` round the buffer up
+ * to 64 KiB page boundaries, so `buffer.byteLength` can exceed `capacity` by up
+ * to a page of trailing slack (see the allocator contract in `allocator.ts`).
+ * Hashing or round-tripping that slack would make two logically-identical
+ * stores with different grow trajectories (or different allocators) diverge,
+ * so we size to `capacity` here.
+ *
+ * Capacity is read live from `store.view` rather than the cached
+ * `store.header` — the in-place grow path bumps the header fields in the
+ * view but leaves `store.header` a stale snapshot (see `grow.ts`).
+ *
+ * The view shares storage with the SAB; subsequent writes to columns are
+ * visible through it. Callers that need a stable snapshot should slice
+ * (`new Uint8Array(view)`) before mutating the store further. */
+export declare function snapshotColumnStore(store: ColumnStore): Uint8Array;
+/** Allocate a fresh backing buffer of `bytes.byteLength`, copy the snapshot
+ * bytes in, validate the header, and reconstruct the `ColumnStore` (header cache +
+ * DataView + per-archetype `ArchetypeViews`).
+ *
+ * `allocator` selects the backing: the default `DEFAULT_SAB_ALLOCATOR`
+ * (`SharedArrayBuffer`) keeps existing callers' behaviour; pass
+ * `heapArraybufferAllocator()` to round-trip a snapshot into a pure-TS heap
+ * world (no SAB required). Either way only one allocation happens — restore
+ * never grows — so a non-in-place allocator is fine here.
+ *
+ * The input can be any `Uint8Array` — a view from `snapshotColumnStore`,
+ * a sliced copy, or bytes read off disk / postMessage. The function
+ * honours `bytes.byteOffset` and `bytes.byteLength`, so passing a
+ * subarray that doesn't start at offset 0 of its backing buffer is
+ * supported.
+ *
+ * Throws `StoreRestoreError` if the bytes are too short for the header,
+ * have the wrong magic, or carry an incompatible `sim_abi_version`. */
+export declare function restoreColumnStore(bytes: Uint8Array, allocator?: BufferAllocator): ColumnStore;
+//# sourceMappingURL=snapshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../../src/core/store/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAUH,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1E,qBAAa,iBAAkB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI3B;AAED;;;;;;;;;;;;;;;;iEAgBiE;AACjE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,CAGlE;AAED;;;;;;;;;;;;;;;;;uEAiBuE;AACvE,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,UAAU,EACjB,SAAS,GAAE,eAAuC,GAChD,WAAW,CAiEb"}

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

@@ -0,0 +1,38 @@
+import { ColumnStore } from './column_store';
+/** FNV-1a 32-bit offset basis (Fowler/Noll/Vo). */
+export declare const FNV1A_OFFSET_BASIS = 2166136261;
+/** FNV-1a 32-bit prime. */
+export declare const FNV1A_PRIME = 16777619;
+/** One FNV-1a round folding a single **byte** (the low 8 bits of `b`) into the
+ * running `hash`: `hash = imul((hash ^ (b & 0xff)) >>> 0, PRIME) >>> 0`. The
+ * single canonical definition of the byte step (#498) — reused by `fnv1a32`
+ * here, by the sparse-store `schemaFingerprint`, and by the server determinism
+ * byte/u32 folds, so the constants and the round live in exactly one place.
+ *
+ * Trivially inlinable (monomorphic, no allocation); the intermediate `>>> 0`s
+ * never change a later round (xor/imul see the same 32-bit pattern signed or
+ * unsigned), they just keep the value unsigned for readers. */
+export declare function fnv1aStep(hash: number, b: number): number;
+/** One FNV-1a round folding a full 32-bit **word** into `hash` — the whole word
+ * xored at once, not four byte rounds. A coarser fold than per-byte FNV-1a, but
+ * equally deterministic and ~4× cheaper, which is why `Store.stateHash` folds
+ * its columns this way (#326). This is the canonical word-step definition its
+ * cold sparse/relation folds call; its hot dense-column inner loop inlines this
+ * exact step for speed and must stay in sync. Same `>>> 0` reasoning as
+ * `fnv1aStep`. */
+export declare function fnv1aStepWord(hash: number, word: number): number;
+/** FNV-1a 32-bit hash of a byte buffer. Returned as an unsigned 32-bit
+ * `number` (i.e. always in `[0, 2^32)`).
+ *
+ * Standalone export so callers that already have a `Uint8Array` (a sliced
+ * snapshot, bytes off disk, a hot subrange) can hash without round-tripping
+ * through `ColumnStore`. */
+export declare function fnv1a32(bytes: Uint8Array): number;
+/** FNV-1a 32-bit hash of the entire SAB region — header + descriptors +
+ * column bytes. The canonical state identifier for cross-replay determinism
+ * checks (#171 plan exit criterion §6.1.7).
+ *
+ * The snapshot view is zero-copy (`snapshotColumnStore` is a view, not a
+ * copy), so this is one scan over the live SAB with no allocation. */
+export declare function columnStoreStateHash(store: ColumnStore): number;
+//# sourceMappingURL=state_hash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state_hash.d.ts","sourceRoot":"","sources":["../../../src/core/store/state_hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAC7C,2BAA2B;AAC3B,eAAO,MAAM,WAAW,WAAa,CAAC;AAEtC;;;;;;;;+DAQ+D;AAC/D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED;;;;;;kBAMkB;AAClB,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhE;AAED;;;;;4BAK4B;AAC5B,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIjD;AAED;;;;;sEAKsE;AACtE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAE/D"}

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

@@ -0,0 +1,38 @@
+import { CreateColumnStoreOptions } from './column_store';
+/** The `StoreHeader` fields that hold a MECHANISM region's byte offset (0 ⇒
+ * region absent). Exactly the four fields a `MechanismRegionSpec` can own; the
+ * always-present `bindings_off` / `layout_descriptor_off` and the generic
+ * `region_table_off` / `region_table_count` pair are not mechanism regions in
+ * this sense and are computed directly outside the loop. */
+export type StoreRegionOffsetField = "command_ring_off" | "entity_index_off" | "event_ring_off" | "action_ring_off";
+/** Mutable accumulator for building `CreateColumnStoreOptions` field by field as
+ * each region reads itself back out of an existing SAB (`readOptions`). */
+export type MutableColumnStoreOptions = {
+    -readonly [K in keyof CreateColumnStoreOptions]: CreateColumnStoreOptions[K];
+};
+/** One engine MECHANISM region. The four closures are the per-region half of
+ * each generic pass; see the module doc for which consumer drives which.
+ *
+ * (Consumer/game regions use the separate self-contained `StoreRegionSpec` in
+ * `region_table.ts` — they carry a precomputed `bytes` + `init` and are
+ * addressed by an opaque `region_id`, not a named header field.) */
+export interface MechanismRegionSpec {
+    /** Stable name — reads in diagnostics and keeps the array self-documenting. */
+    readonly name: string;
+    /** `StoreHeader` field this region's byte offset is written to. */
+    readonly headerOff: StoreRegionOffsetField;
+    /** Byte size implied by `options` (0 ⇒ region absent, so no offset/init). */
+    readonly sizeFromOptions: (options: CreateColumnStoreOptions) => number;
+    /** Initialise the region's header at `off`. Called by `createColumnStore`
+     * only when the region is present (`off !== 0`). */
+    readonly init: (view: DataView, off: number, options: CreateColumnStoreOptions) => void;
+    /** Byte length of an already-allocated region, read from its own header.
+     * Used to snapshot exactly the live bytes before a realloc. */
+    readonly regionBytes: (view: DataView, off: number) => number;
+    /** Re-derive the `CreateColumnStoreOptions` knobs that recreate this region
+     * from an existing SAB, so a realloc lays it out identically. */
+    readonly readOptions: (view: DataView, off: number, out: MutableColumnStoreOptions) => void;
+}
+/** The engine mechanism prefix regions, in SAB byte order (see module doc). */
+export declare const STORE_PREFIX_REGIONS: readonly MechanismRegionSpec[];
+//# sourceMappingURL=store_regions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store_regions.d.ts","sourceRoot":"","sources":["../../../src/core/store/store_regions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAUH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE/D;;;;4DAI4D;AAC5D,MAAM,MAAM,sBAAsB,GAC/B,kBAAkB,GAClB,kBAAkB,GAClB,gBAAgB,GAChB,iBAAiB,CAAC;AAErB;2EAC2E;AAC3E,MAAM,MAAM,yBAAyB,GAAG;IACvC,CAAC,UAAU,CAAC,IAAI,MAAM,wBAAwB,GAAG,wBAAwB,CAAC,CAAC,CAAC;CAC5E,CAAC;AAEF;;;;;oEAKoE;AACpE,MAAM,WAAW,mBAAmB;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;IAC3C,6EAA6E;IAC7E,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,MAAM,CAAC;IACxE;wDACoD;IACpD,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,KAAK,IAAI,CAAC;IACxF;mEAC+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9D;qEACiE;IACjE,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,yBAAyB,KAAK,IAAI,CAAC;CAC5F;AAED,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,EAAE,SAAS,mBAAmB,EAgE9D,CAAC"}