@oasys/oecs 0.3.1 → 0.5.0

package/dist/core/ecs/snapshot_service.d.cts

@@ -0,0 +1,94 @@
+import { Archetype } from './archetype.cjs';
+import { EntityAllocator } from './entity_allocator.cjs';
+import { SparseComponentStore } from './sparse_store.cjs';
+import { RelationStore } from './relation.cjs';
+import { ColumnStore, InPlaceBufferAllocator } from '../store/index.cjs';
+import { HostState } from './resume.cjs';
+/** What the snapshot/resume orchestration needs from `Store` — closure-
+ * injected (the `RelationServiceHost` style). Accessors re-read live fields
+ * per call (the column store and the entity-index views are replaced on
+ * restore); the three mutation members keep Store-owned state transitions on
+ * the Store side. All cold-path. */
+export interface SnapshotHost {
+    readonly sparseStores: () => readonly SparseComponentStore[];
+    readonly relationStores: () => readonly RelationStore[];
+    /** Live SAB generations view (replanted on restore) — for rebuilding
+     * relation ids from entity indices. */
+    readonly generations: () => Int32Array;
+    readonly archetypes: () => readonly Archetype[];
+    readonly columnStore: () => ColumnStore;
+    readonly bufferAllocator: () => InPlaceBufferAllocator;
+    readonly entityIndexCapacity: () => number;
+    readonly tick: () => number;
+    readonly setTick: (tick: number) => void;
+    /** Stamp live row counts into the dense descriptors so a bare dense
+     * reader of the snapshot sees self-consistent counts. */
+    readonly publishRowCounts: () => void;
+    /** Adopt a restored dense store: swap the live backing, refresh archetype
+     * views, recover the allocator high-water from the restored region, and
+     * republish (the grow tail). Owned by Store — see `_mountRestoredDense`. */
+    readonly mountRestoredDense: (restored: ColumnStore) => void;
+    /** Rebuild each archetype's host-side `length`/`enabledCount`/entity-id
+     * back-references from the restored entity-index region + captured host
+     * state. Owned by Store — see `_reconstructHostRows`. */
+    readonly reconstructHostRows: (host: HostState) => void;
+    /** Every archetype's membership just changed — bump the query epoch and
+     * force the next descriptor publish. */
+    readonly invalidateQueryCaches: () => void;
+}
+export declare class SnapshotService {
+    private readonly host;
+    /** The allocator IS its own snapshot seam (H1 step 3): free-list copy on
+     * capture; `setHighWater` + `restoreHostState` on mount. */
+    private readonly allocator;
+    constructor(host: SnapshotHost, allocator: EntityAllocator);
+    /** Serialize the sparse stores **and** relation side data to a self-contained
+     * byte buffer — the sparse half of a world snapshot (the dense half is the
+     * SAB snapshot). Two framed sections: the sparse stores (`snapshotSparseStores`
+     * — exclusive relation targets + multi membership ride here) followed
+     * by the relation side data (`snapshotRelations` — multi forward target
+     * sets, which live outside the sparse store). Both are written in canonical
+     * entity-index order, so two worlds with identical contents inserted in
+     * different orders snapshot byte-for-byte the same (#470). The reverse index
+     * is derived and never serialized — `restoreSparse` rebuilds it. */
+    snapshotSparse(): Uint8Array;
+    /** Repopulate the sparse stores from `snapshotSparse` bytes, replacing all
+     * current sparse data (full-equality round-trip of membership + data), then
+     * rebuild every relation's derived side indices: multi forward sets from the
+     * relation section, and the reverse index for both cardinalities (exclusive
+     * from the just-restored sparse target field, multi from the rebuilt forward
+     * sets). The sparse components and relations must already be registered in
+     * the same order — restore carries data, not the registration (which is
+     * code). Throws `SparseRestoreError` if the snapshot's shape, field identity,
+     * entity-index bounds, or frame length don't validate. */
+    restoreSparse(bytes: Uint8Array): void;
+    /** Rebuild every relation's derived side indices after the sparse stores have
+     * been restored. `restoreRelations` resets all relations, rebuilds the multi
+     * forward sets + their reverse edges from `relBytes`, and validates shape.
+     * The exclusive reverse index can't be carried in the bytes (it's derivable),
+     * so it's rebuilt here from the backing sparse store: every member row holds
+     * `(source index → target EntityID)`, which is exactly one reverse edge. */
+    private rebuildRelationIndices;
+    /** Capture the full live world to one self-contained byte buffer that
+     * `restoreInto` can mount back onto a live, ticking world (#789). Three
+     * sections (see `resume.ts`): the dense SAB column bytes, the sparse +
+     * relation bytes, and the host-side bookkeeping the SAB omits. */
+    snapshot(): Uint8Array;
+    /** Gather the host-side state a snapshot carries alongside the dense + sparse
+     * bytes — see `snapshot()`. The free-list is copied (it's a live mutable). */
+    private collectHostState;
+    /** Mount a `snapshot()` buffer onto the live world and leave it ready to keep
+     * ticking. Fails closed on a malformed frame or a registration mismatch
+     * BEFORE any live state is touched. */
+    restoreInto(bytes: Uint8Array): void;
+    /** Read-only validation of a `snapshotSparse` SECTION (the framed
+     * `[sparseLen][relLen][sparse][rel]` buffer) against the live registry, used
+     * by `restoreInto` to fail closed on a sparse-registration mismatch BEFORE the
+     * dense mount commits. Mirrors `restoreSparse`'s frame check, then validates the
+     * sparse-stores sub-section without mutating. A relation-registration difference
+     * surfaces here too: every `registerRelation` adds a backing sparse store, so a
+     * differing relation set changes the sparse store count / schema. Throws
+     * `SparseRestoreError` on a mismatch. */
+    private assertSparseSectionMatches;
+}
+//# sourceMappingURL=snapshot_service.d.ts.map

package/dist/core/ecs/snapshot_service.d.ts

@@ -0,0 +1,94 @@
+import { Archetype } from './archetype.js';
+import { EntityAllocator } from './entity_allocator.js';
+import { SparseComponentStore } from './sparse_store.js';
+import { RelationStore } from './relation.js';
+import { ColumnStore, InPlaceBufferAllocator } from '../store/index.js';
+import { HostState } from './resume.js';
+/** What the snapshot/resume orchestration needs from `Store` — closure-
+ * injected (the `RelationServiceHost` style). Accessors re-read live fields
+ * per call (the column store and the entity-index views are replaced on
+ * restore); the three mutation members keep Store-owned state transitions on
+ * the Store side. All cold-path. */
+export interface SnapshotHost {
+    readonly sparseStores: () => readonly SparseComponentStore[];
+    readonly relationStores: () => readonly RelationStore[];
+    /** Live SAB generations view (replanted on restore) — for rebuilding
+     * relation ids from entity indices. */
+    readonly generations: () => Int32Array;
+    readonly archetypes: () => readonly Archetype[];
+    readonly columnStore: () => ColumnStore;
+    readonly bufferAllocator: () => InPlaceBufferAllocator;
+    readonly entityIndexCapacity: () => number;
+    readonly tick: () => number;
+    readonly setTick: (tick: number) => void;
+    /** Stamp live row counts into the dense descriptors so a bare dense
+     * reader of the snapshot sees self-consistent counts. */
+    readonly publishRowCounts: () => void;
+    /** Adopt a restored dense store: swap the live backing, refresh archetype
+     * views, recover the allocator high-water from the restored region, and
+     * republish (the grow tail). Owned by Store — see `_mountRestoredDense`. */
+    readonly mountRestoredDense: (restored: ColumnStore) => void;
+    /** Rebuild each archetype's host-side `length`/`enabledCount`/entity-id
+     * back-references from the restored entity-index region + captured host
+     * state. Owned by Store — see `_reconstructHostRows`. */
+    readonly reconstructHostRows: (host: HostState) => void;
+    /** Every archetype's membership just changed — bump the query epoch and
+     * force the next descriptor publish. */
+    readonly invalidateQueryCaches: () => void;
+}
+export declare class SnapshotService {
+    private readonly host;
+    /** The allocator IS its own snapshot seam (H1 step 3): free-list copy on
+     * capture; `setHighWater` + `restoreHostState` on mount. */
+    private readonly allocator;
+    constructor(host: SnapshotHost, allocator: EntityAllocator);
+    /** Serialize the sparse stores **and** relation side data to a self-contained
+     * byte buffer — the sparse half of a world snapshot (the dense half is the
+     * SAB snapshot). Two framed sections: the sparse stores (`snapshotSparseStores`
+     * — exclusive relation targets + multi membership ride here) followed
+     * by the relation side data (`snapshotRelations` — multi forward target
+     * sets, which live outside the sparse store). Both are written in canonical
+     * entity-index order, so two worlds with identical contents inserted in
+     * different orders snapshot byte-for-byte the same (#470). The reverse index
+     * is derived and never serialized — `restoreSparse` rebuilds it. */
+    snapshotSparse(): Uint8Array;
+    /** Repopulate the sparse stores from `snapshotSparse` bytes, replacing all
+     * current sparse data (full-equality round-trip of membership + data), then
+     * rebuild every relation's derived side indices: multi forward sets from the
+     * relation section, and the reverse index for both cardinalities (exclusive
+     * from the just-restored sparse target field, multi from the rebuilt forward
+     * sets). The sparse components and relations must already be registered in
+     * the same order — restore carries data, not the registration (which is
+     * code). Throws `SparseRestoreError` if the snapshot's shape, field identity,
+     * entity-index bounds, or frame length don't validate. */
+    restoreSparse(bytes: Uint8Array): void;
+    /** Rebuild every relation's derived side indices after the sparse stores have
+     * been restored. `restoreRelations` resets all relations, rebuilds the multi
+     * forward sets + their reverse edges from `relBytes`, and validates shape.
+     * The exclusive reverse index can't be carried in the bytes (it's derivable),
+     * so it's rebuilt here from the backing sparse store: every member row holds
+     * `(source index → target EntityID)`, which is exactly one reverse edge. */
+    private rebuildRelationIndices;
+    /** Capture the full live world to one self-contained byte buffer that
+     * `restoreInto` can mount back onto a live, ticking world (#789). Three
+     * sections (see `resume.ts`): the dense SAB column bytes, the sparse +
+     * relation bytes, and the host-side bookkeeping the SAB omits. */
+    snapshot(): Uint8Array;
+    /** Gather the host-side state a snapshot carries alongside the dense + sparse
+     * bytes — see `snapshot()`. The free-list is copied (it's a live mutable). */
+    private collectHostState;
+    /** Mount a `snapshot()` buffer onto the live world and leave it ready to keep
+     * ticking. Fails closed on a malformed frame or a registration mismatch
+     * BEFORE any live state is touched. */
+    restoreInto(bytes: Uint8Array): void;
+    /** Read-only validation of a `snapshotSparse` SECTION (the framed
+     * `[sparseLen][relLen][sparse][rel]` buffer) against the live registry, used
+     * by `restoreInto` to fail closed on a sparse-registration mismatch BEFORE the
+     * dense mount commits. Mirrors `restoreSparse`'s frame check, then validates the
+     * sparse-stores sub-section without mutating. A relation-registration difference
+     * surfaces here too: every `registerRelation` adds a backing sparse store, so a
+     * differing relation set changes the sparse store count / schema. Throws
+     * `SparseRestoreError` on a mismatch. */
+    private assertSparseSectionMatches;
+}
+//# sourceMappingURL=snapshot_service.d.ts.map

package/dist/core/ecs/snapshot_service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot_service.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/snapshot_service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACN,oBAAoB,EAKpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAuC,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,EAGN,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAC3B,MAAM,UAAU,CAAC;AAClB,OAAO,EAON,KAAK,SAAS,EACd,MAAM,UAAU,CAAC;AAElB;;;;oCAIoC;AACpC,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,SAAS,oBAAoB,EAAE,CAAC;IAC7D,QAAQ,CAAC,cAAc,EAAE,MAAM,SAAS,aAAa,EAAE,CAAC;IACxD;2CACuC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,UAAU,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,SAAS,SAAS,EAAE,CAAC;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,WAAW,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,MAAM,sBAAsB,CAAC;IACvD,QAAQ,CAAC,mBAAmB,EAAE,MAAM,MAAM,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC;6DACyD;IACzD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,IAAI,CAAC;IACtC;;gFAE4E;IAC5E,QAAQ,CAAC,kBAAkB,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;IAC7D;;6DAEyD;IACzD,QAAQ,CAAC,mBAAmB,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACxD;4CACwC;IACxC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,IAAI,CAAC;CAC3C;AAED,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC;gEAC4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;gBAEhC,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,eAAe;IAK1D;;;;;;;;wEAQoE;IAC7D,cAAc,IAAI,UAAU;IAanC;;;;;;;;8DAQ0D;IACnD,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAuB7C;;;;;gFAK4E;IAC5E,OAAO,CAAC,sBAAsB;IAW9B;;;sEAGkE;IAC3D,QAAQ,IAAI,UAAU;IAa7B;kFAC8E;IAC9E,OAAO,CAAC,gBAAgB;IAqBxB;;2CAEuC;IAChC,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IA2C3C;;;;;;;6CAOyC;IACzC,OAAO,CAAC,0BAA0B;CAgBlC"}

package/dist/core/ecs/sparse_store.d.cts

@@ -0,0 +1,110 @@
+import { Brand, TypedArrayTag } from '../../type_primitives/index.cjs';
+import { ComponentSchema } from './component.cjs';
+/** Sparse-component handle id. A separate id space from `ComponentID` — it
+ * indexes `Store`'s `sparseStores`, never the archetype mask, which is the
+ * mechanism by which sparse components escape the 128-bit identity cap. */
+export type SparseComponentID = Brand<number, "sparse_component_id">;
+declare const __sparseSchema: unique symbol;
+export type SparseComponentDef<S extends ComponentSchema = ComponentSchema> = SparseComponentID & {
+    readonly [__sparseSchema]: S;
+};
+/** Recover a sparse def's schema type — the sparse sibling of `SchemaOf`
+ * (component.ts), used by the typed `SystemContext` sparse surface. */
+export type SparseSchemaOf<D> = D extends SparseComponentDef<infer S extends ComponentSchema> ? S : never;
+/** One sparse component's membership + data. Pure data structure — the `Store`
+ * owns liveness checks and dev-mode error throwing; this class only knows
+ * entity indices and field rows. */
+export declare class SparseComponentStore {
+    /** entity index → field-value row (length = field count; `[]` for a tag). */
+    private readonly _data;
+    readonly fieldNames: string[];
+    readonly fieldTypes: TypedArrayTag[];
+    readonly fieldIndex: Record<string, number>;
+    constructor(fieldNames: string[], fieldTypes: TypedArrayTag[]);
+    /** Number of entities holding this sparse component. */
+    get size(): number;
+    /** Live entity indices that hold this component (dense, iteration order is
+     * SparseMap insertion/swap order — NOT canonical). Used by the hot query
+     * integration path (#469); for the determinism surface use
+     * `canonicalIndices` instead. */
+    get indices(): readonly number[];
+    /** Live entity indices in **canonical** (ascending) order — the determinism
+     * ordering for `stateHash` + snapshot/restore (ADR-0011, #470). The native
+     * `indices` getter is insertion/swap order and would make two worlds with
+     * identical contents reached by different add/remove histories diverge, so
+     * the cold determinism paths sort here. Allocates a sorted copy each call;
+     * never call it on the hot query path. Indices are 20-bit entity indices,
+     * so the subtraction comparator can't overflow. */
+    canonicalIndices(): number[];
+    /** The field-value row for `index` (length = field count; `[]` for a tag),
+     * or `undefined` if `index` isn't a member. Read-only view for the
+     * determinism paths (`stateHash`, snapshot); mutate via `setField`. */
+    getRow(index: number): readonly number[] | undefined;
+    /** Drop all membership + data. Restore path only — `restoreSparseStores`
+     * repopulates a cleared store from snapshot bytes. */
+    clear(): void;
+    /** Insert the positional field-value `row` for `index`, taking ownership of
+     * the array. Restore path only; bypasses the name→index mapping `setRow`
+     * does, because snapshot bytes are already positional. */
+    setRawRow(index: number, row: number[]): void;
+    has(index: number): boolean;
+    /** Insert or overwrite the row for `index`, building it from `values`.
+     * Fields absent from `values` default to 0; a tag stores `[]`. */
+    setRow(index: number, values: Record<string, number>): void;
+    /** Drop `index`'s membership + data. Returns whether it was present. */
+    remove(index: number): boolean;
+    /** Read one field, or `undefined` if `index` doesn't hold this component. */
+    getField(index: number, fieldIdx: number): number | undefined;
+    /** Write one field. Returns `false` (no-op) if `index` isn't a member. */
+    setField(index: number, fieldIdx: number, value: number): boolean;
+}
+export declare class SparseRestoreError extends Error {
+    constructor(message: string);
+}
+/** Serialize a registry of sparse stores into a self-contained byte buffer —
+ * the **sparse half** of a world snapshot (the dense half is the SAB snapshot,
+ * `snapshotColumnStore`). Members are emitted in canonical (ascending
+ * entity-index) order so the bytes are independent of insertion / removal
+ * history: two worlds with identical sparse contents reached by different
+ * mutation orders serialize byte-for-byte the same (#470).
+ *
+ * Layout (all integers little-endian, to match the dense SAB snapshot and stay
+ * architecture-independent):
+ *
+ *   u32 storeCount
+ *   repeat storeCount times:
+ *     u32 fieldCount
+ *     u32 schemaHash
+ *     u32 memberCount
+ *     repeat memberCount times (canonical entity-index order):
+ *       u32 entityIndex
+ *       f64 × fieldCount   (the positional field row; none for a tag)
+ *
+ * `fieldCount` is redundant with the registered schema but is written so
+ * `restoreSparseStores` can reject a snapshot whose shape doesn't match the
+ * stores it's restoring into; `schemaHash` (a `schemaFingerprint` over the
+ * field names + types) goes further and rejects a buffer whose shape matches
+ * field-for-field but whose field **identity** doesn't (#494). */
+export declare function snapshotSparseStores(stores: readonly SparseComponentStore[]): Uint8Array;
+/** Repopulate already-registered sparse stores from `snapshotSparseStores`
+ * bytes, giving full-equality round-trip (membership + data). The `stores`
+ * registry must already exist with the same shape the snapshot was taken from
+ * — restore replays data into a world whose sparse components are registered
+ * in the same order (the registration is code, not snapshot state). Each store
+ * is cleared first, so restoring is idempotent and drops any pre-existing rows.
+ *
+ * Throws `SparseRestoreError` on any shape or identity mismatch (store count,
+ * field count, schema-hash field identity, an entity index past `MAX_INDEX`,
+ * or a truncated / over-long buffer) rather than silently corrupting state.
+ * The index bound matters because the index keys a `SparseMap` whose backing
+ * array grows to `index` length — an unvalidated crafted u32 (up to ~4.29e9)
+ * would allocate multi-GB (#494). */
+export declare function restoreSparseStores(stores: readonly SparseComponentStore[], bytes: Uint8Array): void;
+/** Read-only validation of a `snapshotSparseStores` buffer against the live
+ * registry, WITHOUT mutating any store (#789). Mirrors `restoreSparseStores`'s
+ * shape/field-identity/index-bounds/frame checks so `Store.restoreInto` can fail
+ * closed on a sparse-registration mismatch BEFORE the dense mount overwrites live
+ * column data. Throws `SparseRestoreError` on any mismatch / malformed buffer. */
+export declare function validateSparseStores(stores: readonly SparseComponentStore[], bytes: Uint8Array): void;
+export {};
+//# sourceMappingURL=sparse_store.d.ts.map

package/dist/core/ecs/sparse_store.d.ts

@@ -0,0 +1,110 @@
+import { Brand, TypedArrayTag } from '../../type_primitives/index.js';
+import { ComponentSchema } from './component.js';
+/** Sparse-component handle id. A separate id space from `ComponentID` — it
+ * indexes `Store`'s `sparseStores`, never the archetype mask, which is the
+ * mechanism by which sparse components escape the 128-bit identity cap. */
+export type SparseComponentID = Brand<number, "sparse_component_id">;
+declare const __sparseSchema: unique symbol;
+export type SparseComponentDef<S extends ComponentSchema = ComponentSchema> = SparseComponentID & {
+    readonly [__sparseSchema]: S;
+};
+/** Recover a sparse def's schema type — the sparse sibling of `SchemaOf`
+ * (component.ts), used by the typed `SystemContext` sparse surface. */
+export type SparseSchemaOf<D> = D extends SparseComponentDef<infer S extends ComponentSchema> ? S : never;
+/** One sparse component's membership + data. Pure data structure — the `Store`
+ * owns liveness checks and dev-mode error throwing; this class only knows
+ * entity indices and field rows. */
+export declare class SparseComponentStore {
+    /** entity index → field-value row (length = field count; `[]` for a tag). */
+    private readonly _data;
+    readonly fieldNames: string[];
+    readonly fieldTypes: TypedArrayTag[];
+    readonly fieldIndex: Record<string, number>;
+    constructor(fieldNames: string[], fieldTypes: TypedArrayTag[]);
+    /** Number of entities holding this sparse component. */
+    get size(): number;
+    /** Live entity indices that hold this component (dense, iteration order is
+     * SparseMap insertion/swap order — NOT canonical). Used by the hot query
+     * integration path (#469); for the determinism surface use
+     * `canonicalIndices` instead. */
+    get indices(): readonly number[];
+    /** Live entity indices in **canonical** (ascending) order — the determinism
+     * ordering for `stateHash` + snapshot/restore (ADR-0011, #470). The native
+     * `indices` getter is insertion/swap order and would make two worlds with
+     * identical contents reached by different add/remove histories diverge, so
+     * the cold determinism paths sort here. Allocates a sorted copy each call;
+     * never call it on the hot query path. Indices are 20-bit entity indices,
+     * so the subtraction comparator can't overflow. */
+    canonicalIndices(): number[];
+    /** The field-value row for `index` (length = field count; `[]` for a tag),
+     * or `undefined` if `index` isn't a member. Read-only view for the
+     * determinism paths (`stateHash`, snapshot); mutate via `setField`. */
+    getRow(index: number): readonly number[] | undefined;
+    /** Drop all membership + data. Restore path only — `restoreSparseStores`
+     * repopulates a cleared store from snapshot bytes. */
+    clear(): void;
+    /** Insert the positional field-value `row` for `index`, taking ownership of
+     * the array. Restore path only; bypasses the name→index mapping `setRow`
+     * does, because snapshot bytes are already positional. */
+    setRawRow(index: number, row: number[]): void;
+    has(index: number): boolean;
+    /** Insert or overwrite the row for `index`, building it from `values`.
+     * Fields absent from `values` default to 0; a tag stores `[]`. */
+    setRow(index: number, values: Record<string, number>): void;
+    /** Drop `index`'s membership + data. Returns whether it was present. */
+    remove(index: number): boolean;
+    /** Read one field, or `undefined` if `index` doesn't hold this component. */
+    getField(index: number, fieldIdx: number): number | undefined;
+    /** Write one field. Returns `false` (no-op) if `index` isn't a member. */
+    setField(index: number, fieldIdx: number, value: number): boolean;
+}
+export declare class SparseRestoreError extends Error {
+    constructor(message: string);
+}
+/** Serialize a registry of sparse stores into a self-contained byte buffer —
+ * the **sparse half** of a world snapshot (the dense half is the SAB snapshot,
+ * `snapshotColumnStore`). Members are emitted in canonical (ascending
+ * entity-index) order so the bytes are independent of insertion / removal
+ * history: two worlds with identical sparse contents reached by different
+ * mutation orders serialize byte-for-byte the same (#470).
+ *
+ * Layout (all integers little-endian, to match the dense SAB snapshot and stay
+ * architecture-independent):
+ *
+ *   u32 storeCount
+ *   repeat storeCount times:
+ *     u32 fieldCount
+ *     u32 schemaHash
+ *     u32 memberCount
+ *     repeat memberCount times (canonical entity-index order):
+ *       u32 entityIndex
+ *       f64 × fieldCount   (the positional field row; none for a tag)
+ *
+ * `fieldCount` is redundant with the registered schema but is written so
+ * `restoreSparseStores` can reject a snapshot whose shape doesn't match the
+ * stores it's restoring into; `schemaHash` (a `schemaFingerprint` over the
+ * field names + types) goes further and rejects a buffer whose shape matches
+ * field-for-field but whose field **identity** doesn't (#494). */
+export declare function snapshotSparseStores(stores: readonly SparseComponentStore[]): Uint8Array;
+/** Repopulate already-registered sparse stores from `snapshotSparseStores`
+ * bytes, giving full-equality round-trip (membership + data). The `stores`
+ * registry must already exist with the same shape the snapshot was taken from
+ * — restore replays data into a world whose sparse components are registered
+ * in the same order (the registration is code, not snapshot state). Each store
+ * is cleared first, so restoring is idempotent and drops any pre-existing rows.
+ *
+ * Throws `SparseRestoreError` on any shape or identity mismatch (store count,
+ * field count, schema-hash field identity, an entity index past `MAX_INDEX`,
+ * or a truncated / over-long buffer) rather than silently corrupting state.
+ * The index bound matters because the index keys a `SparseMap` whose backing
+ * array grows to `index` length — an unvalidated crafted u32 (up to ~4.29e9)
+ * would allocate multi-GB (#494). */
+export declare function restoreSparseStores(stores: readonly SparseComponentStore[], bytes: Uint8Array): void;
+/** Read-only validation of a `snapshotSparseStores` buffer against the live
+ * registry, WITHOUT mutating any store (#789). Mirrors `restoreSparseStores`'s
+ * shape/field-identity/index-bounds/frame checks so `Store.restoreInto` can fail
+ * closed on a sparse-registration mismatch BEFORE the dense mount overwrites live
+ * column data. Throws `SparseRestoreError` on any mismatch / malformed buffer. */
+export declare function validateSparseStores(stores: readonly SparseComponentStore[], bytes: Uint8Array): void;
+export {};
+//# sourceMappingURL=sparse_store.d.ts.map

package/dist/core/ecs/sparse_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparse_store.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/sparse_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KA0BK;AAEL,OAAO,EAAE,KAAK,EAAa,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD;;2EAE2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG,KAAK,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;AAOrE,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAC;AAE5C,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAAI,iBAAiB,GAAG;IACjG,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;CAC7B,CAAC;AAEF;uEACuE;AACvE,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,SAAS,kBAAkB,CAAC,MAAM,CAAC,SAAS,eAAe,CAAC,GAC1F,CAAC,GACD,KAAK,CAAC;AAET;;oCAEoC;AACpC,qBAAa,oBAAoB;IAChC,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,SAAgB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrC,SAAgB,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5C,SAAgB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAEvC,UAAU,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE;IAQ7D,wDAAwD;IACxD,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;qCAGiC;IACjC,IAAW,OAAO,IAAI,SAAS,MAAM,EAAE,CAEtC;IAED;;;;;;uDAMmD;IAC5C,gBAAgB,IAAI,MAAM,EAAE;IAInC;;2EAEuE;IAChE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS;IAI3D;0DACsD;IAC/C,KAAK,IAAI,IAAI;IAIpB;;8DAE0D;IACnD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAI7C,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIlC;sEACkE;IAC3D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAUlE,wEAAwE;IACjE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIrC,6EAA6E;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKpE,0EAA0E;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;CAMxE;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI3B;AAuCD;;;;;;;;;;;;;;;;;;;;;;;kEAuBkE;AAClE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,GAAG,UAAU,CAuCxF;AAED;;;;;;;;;;;;qCAYqC;AACrC,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,SAAS,oBAAoB,EAAE,EACvC,KAAK,EAAE,UAAU,GACf,IAAI,CAkEN;AAED;;;;kFAIkF;AAClF,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,SAAS,oBAAoB,EAAE,EACvC,KAAK,EAAE,UAAU,GACf,IAAI,CA4DN"}