@oasys/oecs 0.5.3 → 0.6.0

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

@@ -2,7 +2,7 @@ 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
+/** Per-archetype resize and 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. */
@@ -11,9 +11,9 @@ export interface ArchetypeGrowSpec {
     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. */
+/** One archetype's column-layout request for `layoutColumnsAtTail`. The caller
+ * resolves `stride`. Grow reuses the old column's stride verbatim. Extend
+ * derives it from `TYPE_TAG_STRIDE[typeTag]` for a brand-new column. */
 export interface TailArchetypeLayout {
     readonly archetypeId: number;
     readonly componentMask: ArchetypeDescriptor["componentMask"];
@@ -25,23 +25,24 @@ export interface TailArchetypeLayout {
         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
+/** Tail-cursor column placement, the single home for the in-place paths'
+ * layout rule and the 2³¹ offset cap. `startCursor` and every offset it
+ * produces are relative to the store base. Starting at `startCursor`
+ * (the current store span), 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
+ * with `rowCount` and `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
+ * the caller must write headers and descriptors through. `growableSabAllocator`
+ * and `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
@@ -51,116 +52,124 @@ export declare function growBufferInPlace(old: ColumnStoreInternal, newTotal: nu
     newView: DataView;
 };
 /**
- * Byte offset where the next appended column region begins — the tail cursor
- * the in-place grow/extend paths pass to `layoutColumnsAtTail`.
+ * Byte offset where the next appended column region begins, measured from the
+ * store base. This is the tail cursor the in-place grow and extend paths pass
+ * to `layoutColumnsAtTail`.
  *
- * For the growable-SAB and wasm backings the buffer is sized to the live extent
- * (`SharedArrayBuffer.grow` resizes exactly; wasm rounds up to a page, and its
- * fast path deliberately lands new regions past that page-rounded tail), so
- * `buffer.byteLength` IS the tail. For the pure-TS **heap** backing (0.5.3) the
- * buffer is a FIXED `ArrayBuffer` reserved at the full cap for V8 fast-path
- * element access, so its `byteLength` is `maxBytes`, NOT the used size — the
- * true tail is the header `capacity` (the logical high-water; new columns land
- * in still-zero fixed-buffer space just past the last live column).
+ * For the growable-SAB and wasm backings the buffer is sized to the live extent,
+ * so `buffer.byteLength` minus the base is the tail. `SharedArrayBuffer.grow`
+ * resizes exactly.
+ * Wasm rounds up to a page, and its fast path deliberately lands new regions
+ * past that page-rounded tail.
  *
- * A plain (non-shared) `ArrayBuffer` is uniquely the heap profile's fixed
- * reservation — every other in-place backing is a `SharedArrayBuffer`. Keying
- * off the backing keeps the SAB/wasm layouts byte-for-byte unchanged.
+ * The pure-TS **heap** backing differs. Its buffer is a fixed `ArrayBuffer`
+ * reserved at the full cap for V8 fast-path element access, so its `byteLength`
+ * is `maxBytes`, not the used size. The true tail is the header `capacity`, the
+ * logical high-water. New columns land in still-zero fixed-buffer space
+ * immediately past the last live column.
+ *
+ * The question is whether the allocator reserved the cap, not which buffer
+ * class it returned: `fixedSabAllocator` reserves a fixed `SharedArrayBuffer`
+ * and needs the header rule, while `growableSabAllocator` grows a
+ * `SharedArrayBuffer` to the live extent and needs the `byteLength` rule. So
+ * the allocator's `reservedAtCap` marker decides. The plain-`ArrayBuffer` test
+ * stays as the fallback for a store whose allocator predates the marker, which
+ * keeps the SAB and wasm layouts byte-for-byte unchanged.
  */
 export declare function tailCursorBytes(old: ColumnStoreInternal): number;
 /**
  * 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
+ * new SAB. Without this, an extend or 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`.
+ * not only the default. Live state (write_head, length, …) is preserved
+ * separately via `snapshotRegions`.
  *
  * 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
+ * (`reservedDescriptorBytes`). 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
+ * Re-reserving the same margin (additive, see `planLayout`) keeps the
  * 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`. */
+ * region's offset. `consumer` is keyed by `region_id` (consumer regions have no
+ * named header field). Pairs `snapshotRegions` with
+ * `restoreRegions`. */
 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
+ * 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
+ * an allocator-induced detach. `restoreRegions` places it back at the
  * matching offset in the new SAB.
  *
- * Header bytes themselves are NOT snapshotted — `createColumnStore` writes the
+ * 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;
+export declare function snapshotRegions(old: ColumnStore): PrefixRegionSnapshot;
 /** Restore prefix-region byte snapshots into `newStore` at the matching
- * region offsets. Pairs with `snapshotPrefixRegions`. The new SAB's regions
+ * region offsets. Pairs with `snapshotRegions`. 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,
+ * 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;
+export declare function restoreRegions(newStore: ColumnStore, snap: PrefixRegionSnapshot): void;
 /**
- * Snapshot per-archetype live column bytes from `old` BEFORE any
+ * 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.
+ * 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
+ * into `newStore`'s column views. The snapshot's column order must match
+ * the new archetype's `columnsInOrder` (extend and grow guarantee this
  * because they carry the column spec forward unchanged).
  */
-export declare function restoreColumnSnapshots(newStore: ColumnStore, snapshots: Map<number, Uint8Array[]>): void;
+export declare function restoreLiveColumns(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
+ * `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
+ *   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
+ *      contract `Store` relies on to keep its entity table across resizes.
+ *      `optionsFromOld` re-reserves the regions and the descriptor headroom,
+ *      so the republished store keeps its layout and its 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
+ *      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` /
+ *      header so its cached `viewStamp` matches the bytes written above.
+ *      `createColumnStore` stamped it 0. `capacity` and
  *      `archetype_count` are already correct (createColumnStore sized them),
- *      so the spread carries them — and the internal `_allocator` /
- *      `_regionBytes` fields — through unchanged.
+ *      so the spread carries them, and the internal `_allocator` and
+ *      `_regionBytes` fields, through unchanged.
  *
- * Every view in the returned store is fresh; callers MUST refresh
- * (`viewsPreserved: false` is the callers' contract with THEIR callers).
+ * 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;

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

@@ -2,7 +2,7 @@ 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
+/** Per-archetype resize and 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. */
@@ -11,9 +11,9 @@ export interface ArchetypeGrowSpec {
     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. */
+/** One archetype's column-layout request for `layoutColumnsAtTail`. The caller
+ * resolves `stride`. Grow reuses the old column's stride verbatim. Extend
+ * derives it from `TYPE_TAG_STRIDE[typeTag]` for a brand-new column. */
 export interface TailArchetypeLayout {
     readonly archetypeId: number;
     readonly componentMask: ArchetypeDescriptor["componentMask"];
@@ -25,23 +25,24 @@ export interface TailArchetypeLayout {
         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
+/** Tail-cursor column placement, the single home for the in-place paths'
+ * layout rule and the 2³¹ offset cap. `startCursor` and every offset it
+ * produces are relative to the store base. Starting at `startCursor`
+ * (the current store span), 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
+ * with `rowCount` and `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
+ * the caller must write headers and descriptors through. `growableSabAllocator`
+ * and `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
@@ -51,116 +52,124 @@ export declare function growBufferInPlace(old: ColumnStoreInternal, newTotal: nu
     newView: DataView;
 };
 /**
- * Byte offset where the next appended column region begins — the tail cursor
- * the in-place grow/extend paths pass to `layoutColumnsAtTail`.
+ * Byte offset where the next appended column region begins, measured from the
+ * store base. This is the tail cursor the in-place grow and extend paths pass
+ * to `layoutColumnsAtTail`.
  *
- * For the growable-SAB and wasm backings the buffer is sized to the live extent
- * (`SharedArrayBuffer.grow` resizes exactly; wasm rounds up to a page, and its
- * fast path deliberately lands new regions past that page-rounded tail), so
- * `buffer.byteLength` IS the tail. For the pure-TS **heap** backing (0.5.3) the
- * buffer is a FIXED `ArrayBuffer` reserved at the full cap for V8 fast-path
- * element access, so its `byteLength` is `maxBytes`, NOT the used size — the
- * true tail is the header `capacity` (the logical high-water; new columns land
- * in still-zero fixed-buffer space just past the last live column).
+ * For the growable-SAB and wasm backings the buffer is sized to the live extent,
+ * so `buffer.byteLength` minus the base is the tail. `SharedArrayBuffer.grow`
+ * resizes exactly.
+ * Wasm rounds up to a page, and its fast path deliberately lands new regions
+ * past that page-rounded tail.
  *
- * A plain (non-shared) `ArrayBuffer` is uniquely the heap profile's fixed
- * reservation — every other in-place backing is a `SharedArrayBuffer`. Keying
- * off the backing keeps the SAB/wasm layouts byte-for-byte unchanged.
+ * The pure-TS **heap** backing differs. Its buffer is a fixed `ArrayBuffer`
+ * reserved at the full cap for V8 fast-path element access, so its `byteLength`
+ * is `maxBytes`, not the used size. The true tail is the header `capacity`, the
+ * logical high-water. New columns land in still-zero fixed-buffer space
+ * immediately past the last live column.
+ *
+ * The question is whether the allocator reserved the cap, not which buffer
+ * class it returned: `fixedSabAllocator` reserves a fixed `SharedArrayBuffer`
+ * and needs the header rule, while `growableSabAllocator` grows a
+ * `SharedArrayBuffer` to the live extent and needs the `byteLength` rule. So
+ * the allocator's `reservedAtCap` marker decides. The plain-`ArrayBuffer` test
+ * stays as the fallback for a store whose allocator predates the marker, which
+ * keeps the SAB and wasm layouts byte-for-byte unchanged.
  */
 export declare function tailCursorBytes(old: ColumnStoreInternal): number;
 /**
  * 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
+ * new SAB. Without this, an extend or 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`.
+ * not only the default. Live state (write_head, length, …) is preserved
+ * separately via `snapshotRegions`.
  *
  * 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
+ * (`reservedDescriptorBytes`). 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
+ * Re-reserving the same margin (additive, see `planLayout`) keeps the
  * 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`. */
+ * region's offset. `consumer` is keyed by `region_id` (consumer regions have no
+ * named header field). Pairs `snapshotRegions` with
+ * `restoreRegions`. */
 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
+ * 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
+ * an allocator-induced detach. `restoreRegions` places it back at the
  * matching offset in the new SAB.
  *
- * Header bytes themselves are NOT snapshotted — `createColumnStore` writes the
+ * 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;
+export declare function snapshotRegions(old: ColumnStore): PrefixRegionSnapshot;
 /** Restore prefix-region byte snapshots into `newStore` at the matching
- * region offsets. Pairs with `snapshotPrefixRegions`. The new SAB's regions
+ * region offsets. Pairs with `snapshotRegions`. 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,
+ * 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;
+export declare function restoreRegions(newStore: ColumnStore, snap: PrefixRegionSnapshot): void;
 /**
- * Snapshot per-archetype live column bytes from `old` BEFORE any
+ * 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.
+ * 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
+ * into `newStore`'s column views. The snapshot's column order must match
+ * the new archetype's `columnsInOrder` (extend and grow guarantee this
  * because they carry the column spec forward unchanged).
  */
-export declare function restoreColumnSnapshots(newStore: ColumnStore, snapshots: Map<number, Uint8Array[]>): void;
+export declare function restoreLiveColumns(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
+ * `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
+ *   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
+ *      contract `Store` relies on to keep its entity table across resizes.
+ *      `optionsFromOld` re-reserves the regions and the descriptor headroom,
+ *      so the republished store keeps its layout and its 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
+ *      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` /
+ *      header so its cached `viewStamp` matches the bytes written above.
+ *      `createColumnStore` stamped it 0. `capacity` and
  *      `archetype_count` are already correct (createColumnStore sized them),
- *      so the spread carries them — and the internal `_allocator` /
- *      `_regionBytes` fields — through unchanged.
+ *      so the spread carries them, and the internal `_allocator` and
+ *      `_regionBytes` fields, through unchanged.
  *
- * Every view in the returned store is fresh; callers MUST refresh
- * (`viewsPreserved: false` is the callers' contract with THEIR callers).
+ * 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;

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

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

@@ -4,40 +4,46 @@ export { REGION_TABLE_ENTRY_BYTES, REGION_TABLE_ENTRY_OFFSETS };
  * 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
+ * `init` runs once at first allocation. Across a SAB grow and 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
+ * 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`. */
+    /** Consumer-owned region id (nonzero, distinct). Written to the directory
+     * resolved by the consumer through `findRegionOffset`. */
     readonly id: number;
-    /** Human label for diagnostics / the self-documenting directory dump. */
+    /** Human label for diagnostics and 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`. */
+    /** Initialise the region header and seed bytes at `off`, which indexes
+     * `view`. `view` starts at the store base, so a consumer that needs a
+     * TypedArray builds it at `view.byteOffset + off`. */
     readonly init: (view: DataView, off: number) => void;
 }
-/** One decoded directory record. */
+/** One decoded directory record. `byteOffset` is measured from the store base,
+ * the same as every other offset in the bytes. */
 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
+/** A resolved handle to a consumer region, returned by `ECS.regionHandle` or
+ * `Store.regionHandle`. Carries the live `buffer` and `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). */
+ * directory. Re-fetch after a SAB grow (the offset and 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
+    /** `ArrayBufferLike`, see `ColumnStore.buffer`. Consumer regions are a SAB-profile
+     * feature (WASM or 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;
+    /** Starts at the store base, so `view.byteOffset` is that base. */
     readonly view: DataView;
+    /** Buffer-absolute, so `new Uint8Array(buffer, offset, bytes)` reads the
+     * region. Read it through `view` at `offset - view.byteOffset`. */
     readonly offset: number;
     readonly bytes: number;
 }
@@ -48,9 +54,9 @@ export declare class RegionRegistryError extends Error {
 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 —
+ * 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;
+export declare function assertRegionSpecs(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`. */
@@ -59,16 +65,17 @@ export declare function readRegionTableEntry(view: DataView, off: number): Regio
 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` /
+/** Read the directory described by the SAB header (`region_table_off` and
  * `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). */
+/** Resolve a consumer region's store-relative byte offset by `region_id`, or 0
+ * when absent (no directory, or no matching entry). The TS twin of the
+ * module-side lookup. 0 is an unambiguous "absent"
+ * sentinel because a real region never starts at relative offset 0, which the
+ * header occupies. */
 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. */
+ * materialise a TypedArray view) and not only its start. */
 export declare function findRegionEntry(view: DataView, regionId: number): RegionTableEntry | null;
 //# sourceMappingURL=region_table.d.ts.map