@oasys/oecs 0.3.1 → 0.5.0

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

@@ -0,0 +1,17 @@
+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.js';
+export { type StoreRegionSpec, type RegionTableEntry, type ColumnStoreRegionHandle, RegionRegistryError, regionTableBytes, validateRegionSpecs, writeRegionTableEntry, readRegionTableEntry, writeRegionTable, readRegionTable, readHeaderRegionTable, findRegionOffset, findRegionEntry } from './region_table.js';
+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.js';
+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.js';
+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.js';
+export { ENTITY_INDEX_HEADER_BYTES, ENTITY_INDEX_BYTES_PER_SLOT, ENTITY_INDEX_HEADER_OFFSETS, EntityIndexError, buildEntityIndexViews, entityIndexCapacity, entityIndexLength, entityIndexRegionBytes, initEntityIndexRegion, setEntityIndexLength } from './entity_index.js';
+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.js';
+export { type PayloadCodec, CommandDispatcher } from './command_dispatch.js';
+export { BufferBackedColumn, StoreColumnOverflowError } from './buffer_backed_column.js';
+export { type ArchetypeGrowSpec, type GrowPlan, type GrowResult, StoreGrowError, growColumnStore } from './grow.js';
+export { type ExtendPlan, type ExtendResult, StoreExtendError, extendColumnStore } from './extend.js';
+export { snapshotLiveColumns, restoreColumnSnapshots } from './layout_ops.js';
+export { type BufferAllocator, type InPlaceBufferAllocator, StoreCapExceededError, SabUnavailableError, DEFAULT_SAB_ALLOCATOR, wasmMemoryAllocator, growableSabAllocator, heapArraybufferAllocator } from './allocator.js';
+export { StoreRestoreError, snapshotColumnStore, restoreColumnStore } from './snapshot.js';
+export { FNV1A_OFFSET_BASIS, FNV1A_PRIME, fnv1a32, fnv1aStep, fnv1aStepWord, columnStoreStateHash } from './state_hash.js';
+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.js';
+//# 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/layout_ops.d.cts

@@ -0,0 +1,152 @@
+import { BufferAllocator } from './allocator.cjs';
+import { ArchetypeSpec, ColumnStore, ColumnStoreInternal, CreateColumnStoreOptions } from './column_store.cjs';
+import { ArchetypeDescriptor, TypeTagValue } from './descriptor.cjs';
+import { StoreRegionOffsetField } from './store_regions.cjs';
+/** Per-archetype resize/copy input, shared by `GrowPlan.archetypes` and
+ * `ExtendPlan.existing` (so callers can reuse plan-building helpers). The
+ * caller picks the new `row_capacity` and declares the current live
+ * `row_count` so the copy knows how many rows matter. */
+export interface ArchetypeGrowSpec {
+    readonly archetypeId: number;
+    readonly newRowCapacity: number;
+    readonly rowCount: number;
+}
+/** One archetype's column-layout request for `layoutColumnsAtTail`. `stride`
+ * is resolved by the caller — grow reuses the old column's stride verbatim;
+ * extend derives it from `TYPE_TAG_STRIDE[typeTag]` for brand-new columns. */
+export interface TailArchetypeLayout {
+    readonly archetypeId: number;
+    readonly componentMask: ArchetypeDescriptor["componentMask"];
+    readonly rowCapacity: number;
+    readonly columns: readonly {
+        readonly componentId: number;
+        readonly fieldId: number;
+        readonly typeTag: TypeTagValue;
+        readonly stride: number;
+    }[];
+}
+/** Tail-cursor column placement — the single home for the in-place paths'
+ * layout rule and the 2³¹ offset cap (#382). Starting at `startCursor`
+ * (the current buffer byteLength), each archetype's columns are placed
+ * `alignUp(cursor, stride)` then advanced by `stride * rowCapacity`; the
+ * final tail (last column's advance, not re-aligned) becomes the grown
+ * buffer's byteLength and is guarded past `STORE_MAX_BYTE_OFFSET` exactly
+ * like `planLayout` guards the create-time layout. Descriptors come back
+ * with `rowCount` / `enabledCount` zeroed (the store side of those counters
+ * lives with the caller). */
+export declare function layoutColumnsAtTail(startCursor: number, archetypes: readonly TailArchetypeLayout[]): {
+    descriptors: ArchetypeDescriptor[];
+    newTotal: number;
+};
+/** Grow an in-place-backed store's buffer to `newTotal` and mint the DataView
+ * the caller must write headers/descriptors through. `growableSabAllocator` /
+ * `heapArraybufferAllocator` return the SAME buffer instance grown in place;
+ * `wasmMemoryAllocator` returns a NEW ref over the same linear memory — old
+ * typed-array views stay valid either way (the `isInPlace` contract), but
+ * when the ref changed the old DataView's byteLength is frozen at the
+ * pre-grow size, so a fresh DataView over the new ref is required for any
+ * write past that boundary. */
+export declare function growBufferInPlace(old: ColumnStoreInternal, newTotal: number): {
+    grownBuffer: ArrayBufferLike;
+    newView: DataView;
+};
+/**
+ * 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.
+ */
+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;
+/**
+ * The realloc-and-republish slow path shared by `growColumnStore` and
+ * `extendColumnStore` — everything between "the specs are decided" and "the
+ * caller shapes its result":
+ *
+ *   1. Capture `view_stamp` and snapshot live rows AND prefix regions
+ *      (command ring, entity-index) BEFORE the allocator call — the
+ *      wasmMemoryAllocator may detach `old`'s views on grow, so everything
+ *      needed is captured first. The prefix-region preservation is the
+ *      contract `Store` relies on to keep its entity table across resizes
+ *      (#245); `optionsFromOld` re-reserves regions and descriptor headroom
+ *      (#541) so the republished store keeps its layout and fast paths.
+ *   2. `createColumnStore` with the derived options (fresh buffer; the same
+ *      growable allocator carries forward so the new buffer also grows in
+ *      place).
+ *   3. Restore live rows + prefix regions. Archetypes without a row count
+ *      contributed no snapshot and stay zero-initialised; prefix regions
+ *      overwrite the empty state `createColumnStore` initialised.
+ *   4. Bump `view_stamp` from the pre-capture value and patch the returned
+ *      header so its cached `viewStamp` matches the buffer bytes just
+ *      written — `createColumnStore` stamped it 0 (#386). `capacity` /
+ *      `archetype_count` are already correct (createColumnStore sized them),
+ *      so the spread carries them — and the internal `_allocator` /
+ *      `_regionBytes` fields — through unchanged.
+ *
+ * Every view in the returned store is fresh; callers MUST refresh
+ * (`viewsPreserved: false` is the callers' contract with THEIR callers).
+ */
+export declare function reallocAndRepublish(old: ColumnStore, specs: readonly ArchetypeSpec[], rowCountsById: Map<number, number>, allocator: BufferAllocator | undefined): {
+    store: ColumnStore;
+    oldViewStamp: number;
+    newViewStamp: number;
+};
+//# sourceMappingURL=layout_ops.d.ts.map

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

@@ -0,0 +1,152 @@
+import { BufferAllocator } from './allocator.js';
+import { ArchetypeSpec, ColumnStore, ColumnStoreInternal, CreateColumnStoreOptions } from './column_store.js';
+import { ArchetypeDescriptor, TypeTagValue } from './descriptor.js';
+import { StoreRegionOffsetField } from './store_regions.js';
+/** Per-archetype resize/copy input, shared by `GrowPlan.archetypes` and
+ * `ExtendPlan.existing` (so callers can reuse plan-building helpers). The
+ * caller picks the new `row_capacity` and declares the current live
+ * `row_count` so the copy knows how many rows matter. */
+export interface ArchetypeGrowSpec {
+    readonly archetypeId: number;
+    readonly newRowCapacity: number;
+    readonly rowCount: number;
+}
+/** One archetype's column-layout request for `layoutColumnsAtTail`. `stride`
+ * is resolved by the caller — grow reuses the old column's stride verbatim;
+ * extend derives it from `TYPE_TAG_STRIDE[typeTag]` for brand-new columns. */
+export interface TailArchetypeLayout {
+    readonly archetypeId: number;
+    readonly componentMask: ArchetypeDescriptor["componentMask"];
+    readonly rowCapacity: number;
+    readonly columns: readonly {
+        readonly componentId: number;
+        readonly fieldId: number;
+        readonly typeTag: TypeTagValue;
+        readonly stride: number;
+    }[];
+}
+/** Tail-cursor column placement — the single home for the in-place paths'
+ * layout rule and the 2³¹ offset cap (#382). Starting at `startCursor`
+ * (the current buffer byteLength), each archetype's columns are placed
+ * `alignUp(cursor, stride)` then advanced by `stride * rowCapacity`; the
+ * final tail (last column's advance, not re-aligned) becomes the grown
+ * buffer's byteLength and is guarded past `STORE_MAX_BYTE_OFFSET` exactly
+ * like `planLayout` guards the create-time layout. Descriptors come back
+ * with `rowCount` / `enabledCount` zeroed (the store side of those counters
+ * lives with the caller). */
+export declare function layoutColumnsAtTail(startCursor: number, archetypes: readonly TailArchetypeLayout[]): {
+    descriptors: ArchetypeDescriptor[];
+    newTotal: number;
+};
+/** Grow an in-place-backed store's buffer to `newTotal` and mint the DataView
+ * the caller must write headers/descriptors through. `growableSabAllocator` /
+ * `heapArraybufferAllocator` return the SAME buffer instance grown in place;
+ * `wasmMemoryAllocator` returns a NEW ref over the same linear memory — old
+ * typed-array views stay valid either way (the `isInPlace` contract), but
+ * when the ref changed the old DataView's byteLength is frozen at the
+ * pre-grow size, so a fresh DataView over the new ref is required for any
+ * write past that boundary. */
+export declare function growBufferInPlace(old: ColumnStoreInternal, newTotal: number): {
+    grownBuffer: ArrayBufferLike;
+    newView: DataView;
+};
+/**
+ * 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.
+ */
+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;
+/**
+ * The realloc-and-republish slow path shared by `growColumnStore` and
+ * `extendColumnStore` — everything between "the specs are decided" and "the
+ * caller shapes its result":
+ *
+ *   1. Capture `view_stamp` and snapshot live rows AND prefix regions
+ *      (command ring, entity-index) BEFORE the allocator call — the
+ *      wasmMemoryAllocator may detach `old`'s views on grow, so everything
+ *      needed is captured first. The prefix-region preservation is the
+ *      contract `Store` relies on to keep its entity table across resizes
+ *      (#245); `optionsFromOld` re-reserves regions and descriptor headroom
+ *      (#541) so the republished store keeps its layout and fast paths.
+ *   2. `createColumnStore` with the derived options (fresh buffer; the same
+ *      growable allocator carries forward so the new buffer also grows in
+ *      place).
+ *   3. Restore live rows + prefix regions. Archetypes without a row count
+ *      contributed no snapshot and stay zero-initialised; prefix regions
+ *      overwrite the empty state `createColumnStore` initialised.
+ *   4. Bump `view_stamp` from the pre-capture value and patch the returned
+ *      header so its cached `viewStamp` matches the buffer bytes just
+ *      written — `createColumnStore` stamped it 0 (#386). `capacity` /
+ *      `archetype_count` are already correct (createColumnStore sized them),
+ *      so the spread carries them — and the internal `_allocator` /
+ *      `_regionBytes` fields — through unchanged.
+ *
+ * Every view in the returned store is fresh; callers MUST refresh
+ * (`viewsPreserved: false` is the callers' contract with THEIR callers).
+ */
+export declare function reallocAndRepublish(old: ColumnStore, specs: readonly ArchetypeSpec[], rowCountsById: Map<number, number>, allocator: BufferAllocator | undefined): {
+    store: ColumnStore;
+    oldViewStamp: number;
+    newViewStamp: number;
+};
+//# sourceMappingURL=layout_ops.d.ts.map

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

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

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

@@ -0,0 +1,74 @@
+import { REGION_TABLE_ENTRY_BYTES, REGION_TABLE_ENTRY_OFFSETS } from './vendored_abi/abi.cjs';
+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

@@ -0,0 +1,74 @@
+import { REGION_TABLE_ENTRY_BYTES, REGION_TABLE_ENTRY_OFFSETS } from './vendored_abi/abi.js';
+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,oBAAoB,CAAC;AAE5B,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.cts

@@ -0,0 +1,43 @@
+import { ColumnStore } from './column_store.cjs';
+import { BufferAllocator } from './allocator.cjs';
+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

@@ -0,0 +1,43 @@
+import { ColumnStore } from './column_store.js';
+import { BufferAllocator } from './allocator.js';
+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.cts

@@ -0,0 +1,38 @@
+import { ColumnStore } from './column_store.cjs';
+/** 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