@oasys/oecs 0.3.0 → 0.4.0

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

@@ -0,0 +1,107 @@
+import { Brand, TypedArrayTag } from '../../type_primitives';
+import { ComponentSchema } from './component';
+/** 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;
+};
+/** 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;;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"}