@woosh/meep-engine 2.164.0 → 2.165.1

package/src/engine/ecs/storage/binary/object-v2/BinaryObjectSerializer.js

@@ -0,0 +1,331 @@
+import { assert } from "../../../../../core/assert.js";
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+import { writeObjectString } from "./objectStringCodec.js";
+import {
+    OBJECT_FORMAT_VERSION,
+    OBJECT_MAGIC,
+    TAG_ADAPTER_OBJECT,
+    TAG_ARRAY,
+    TAG_BIGINT,
+    TAG_FALSE,
+    TAG_FLOAT,
+    TAG_NEG_INT,
+    TAG_NULL,
+    TAG_PLAIN_OBJECT,
+    TAG_POS_INT,
+    TAG_REF,
+    TAG_REFLECT_OBJECT,
+    TAG_STRING,
+    TAG_TRUE,
+    TAG_UNDEFINED
+} from "./ObjectBinaryFormat.js";
+
+/**
+ * Largest integer magnitude that {@link BinaryBuffer.writeUintVar} accepts; larger integers fall back to float64.
+ * @readonly
+ * @type {number}
+ */
+const MAX_VARINT = 2147483647;
+
+/**
+ * Writer half of the general object-graph binary serializer. See {@link BinaryObjectDeSerializer} for the reader
+ * and `DESIGN.md` for the wire format and rationale.
+ *
+ * Serializes an arbitrary value — primitives, arrays, plain objects and class instances — with **no per-class
+ * setup required**. Class instances are serialized by reflection over their own enumerable fields by default; if a
+ * class has a hand-written adapter registered in the {@link BinarySerializationRegistry}, that adapter is used
+ * instead (compact, custom, versioned). Shared references and cycles are preserved via first-seen object indices.
+ *
+ * Class names and reflective field-name sets are interned into two tables that are written ahead of the body, so
+ * repeated types cost their name once. The body is built into a scratch buffer first and copied in after the
+ * tables — the only extra work versus single-pass is that final byte copy.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BinaryObjectSerializer {
+
+    /**
+     * Adapter + migrator + class-name registry.
+     * @type {BinarySerializationRegistry|null}
+     */
+    #registry = null;
+
+    /**
+     * Scratch buffer the value graph (body) is written into before it is copied in after the tables.
+     * @type {BinaryBuffer}
+     */
+    #body = new BinaryBuffer();
+
+    /**
+     * Object/array instance -> its assigned index, for reference de-duplication and cycle detection.
+     * @type {Map<Object, number>}
+     */
+    #refs = new Map();
+
+    /**
+     * typeName -> class-table index.
+     * @type {Map<string, number>}
+     */
+    #classIndex = new Map();
+
+    /**
+     * Ordered class-table records, flushed ahead of the body.
+     * @type {Array<{typeName:string, version:number}>}
+     */
+    #classList = [];
+
+    /**
+     * shape key (JSON of the field-name list) -> shape-table index.
+     * @type {Map<string, number>}
+     */
+    #shapeIndex = new Map();
+
+    /**
+     * Ordered shape-table records (each an ordered field-name list), flushed ahead of the body.
+     * @type {Array<string[]>}
+     */
+    #shapeList = [];
+
+    /**
+     * @param {BinarySerializationRegistry} registry
+     */
+    constructor(registry) {
+        this.setRegistry(registry);
+    }
+
+    /**
+     * @param {BinarySerializationRegistry} registry
+     */
+    setRegistry(registry) {
+        assert.defined(registry, 'registry');
+        assert.ok(registry.isBinarySerializationRegistry, 'registry is not a BinarySerializationRegistry');
+
+        this.#registry = registry;
+    }
+
+    #reset() {
+        this.#body.position = 0;
+        this.#refs.clear();
+        this.#classIndex.clear();
+        this.#classList.length = 0;
+        this.#shapeIndex.clear();
+        this.#shapeList.length = 0;
+    }
+
+    /**
+     * Serialize `value` and its whole object graph into `buffer` as a complete document (header + tables + body).
+     *
+     * @param {BinaryBuffer} buffer target, written at the current {@link BinaryBuffer.position}
+     * @param {*} value any value; objects may be plain, class instances (reflective or adapter-backed) or arrays
+     */
+    serialize(buffer, value) {
+        this.#reset();
+
+        // build the body first so the interning tables are complete before we emit them
+        this.writeValue(this.#body, value);
+
+        // header
+        buffer.writeUint16(OBJECT_MAGIC);
+        buffer.writeUint8(OBJECT_FORMAT_VERSION);
+
+        // class table
+        buffer.writeUintVar(this.#classList.length);
+        for (let i = 0; i < this.#classList.length; i++) {
+            const record = this.#classList[i];
+            writeObjectString(buffer, record.typeName);
+            buffer.writeUintVar(record.version);
+        }
+
+        // shape table
+        buffer.writeUintVar(this.#shapeList.length);
+        for (let i = 0; i < this.#shapeList.length; i++) {
+            const names = this.#shapeList[i];
+            buffer.writeUintVar(names.length);
+            for (let j = 0; j < names.length; j++) {
+                writeObjectString(buffer, names[j]);
+            }
+        }
+
+        // body
+        buffer.writeBytes(this.#body.raw_bytes, 0, this.#body.position);
+    }
+
+    /**
+     * @param {string} typeName
+     * @param {number} version
+     * @returns {number} class-table index
+     */
+    #internClass(typeName, version) {
+        let index = this.#classIndex.get(typeName);
+
+        if (index === undefined) {
+            index = this.#classList.length;
+            this.#classList.push({ typeName, version });
+            this.#classIndex.set(typeName, index);
+        }
+
+        return index;
+    }
+
+    /**
+     * @param {string[]} names ordered field names
+     * @returns {number} shape-table index
+     */
+    #internShape(names) {
+        const key = JSON.stringify(names);
+
+        let index = this.#shapeIndex.get(key);
+
+        if (index === undefined) {
+            index = this.#shapeList.length;
+            this.#shapeList.push(names);
+            this.#shapeIndex.set(key, index);
+        }
+
+        return index;
+    }
+
+    /**
+     * Write a single value. Nesting adapters call this to serialize a child of any type (including `null`).
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {*} value
+     */
+    writeValue(buffer, value) {
+        if (value === null) {
+            buffer.writeUint8(TAG_NULL);
+            return;
+        }
+
+        const type = typeof value;
+
+        switch (type) {
+            case "undefined":
+                buffer.writeUint8(TAG_UNDEFINED);
+                return;
+            case "boolean":
+                buffer.writeUint8(value ? TAG_TRUE : TAG_FALSE);
+                return;
+            case "number":
+                if (Number.isInteger(value) && value >= -MAX_VARINT && value <= MAX_VARINT) {
+                    if (value >= 0) {
+                        buffer.writeUint8(TAG_POS_INT);
+                        buffer.writeUintVar(value);
+                    } else {
+                        buffer.writeUint8(TAG_NEG_INT);
+                        buffer.writeUintVar(-value);
+                    }
+                } else {
+                    buffer.writeUint8(TAG_FLOAT);
+                    buffer.writeFloat64(value);
+                }
+                return;
+            case "string":
+                buffer.writeUint8(TAG_STRING);
+                writeObjectString(buffer, value);
+                return;
+            case "bigint":
+                buffer.writeUint8(TAG_BIGINT);
+                writeObjectString(buffer, value.toString());
+                return;
+            case "function":
+                throw new Error("Cannot serialize a function value");
+            case "symbol":
+                throw new Error("Cannot serialize a symbol value");
+            default:
+            // object, handled below
+        }
+
+        // from here `value` is a non-null object (or array)
+
+        const existingIndex = this.#refs.get(value);
+
+        if (existingIndex !== undefined) {
+            // seen before — emit a back-reference (handles shared references and cycles)
+            buffer.writeUint8(TAG_REF);
+            buffer.writeUintVar(existingIndex);
+            return;
+        }
+
+        // assign this instance its index BEFORE writing contents, so a cyclic child can refer back to it
+        this.#refs.set(value, this.#refs.size);
+
+        if (Array.isArray(value)) {
+            buffer.writeUint8(TAG_ARRAY);
+            buffer.writeUintVar(value.length);
+            for (let i = 0; i < value.length; i++) {
+                this.writeValue(buffer, value[i]);
+            }
+            return;
+        }
+
+        const prototype = Object.getPrototypeOf(value);
+        const ctor = prototype === null ? undefined : prototype.constructor;
+
+        // prefer the adapter-registered name (survives minification, keyed on the constructor), then the class's
+        // own static typeName (the deliberate escape hatch from name mangling). The typeName must be OWN, not
+        // inherited: a subclass without its own typeName would otherwise be misclassified as its ancestor.
+        let typeName = this.#registry.getClassName(ctor);
+        if (typeName === undefined && ctor !== undefined && Object.prototype.hasOwnProperty.call(ctor, "typeName")) {
+            typeName = ctor.typeName;
+        }
+
+        if (typeName !== undefined && typeName !== null) {
+            const adapter = this.#registry.getAdapter(typeName);
+
+            if (adapter !== undefined) {
+                // hand-written adapter takes over the payload layout for this class
+                const classIdx = this.#internClass(typeName, adapter.version);
+                buffer.writeUint8(TAG_ADAPTER_OBJECT);
+                buffer.writeUintVar(classIdx);
+                adapter.initialize(this);
+                adapter.serialize(buffer, value);
+                return;
+            }
+
+            // reflective class instance — reconstructed via the module registry on read
+            this.#writeReflected(buffer, TAG_REFLECT_OBJECT, this.#internClass(typeName, 0), value);
+            return;
+        }
+
+        if (prototype === Object.prototype || prototype === null) {
+            // plain object — reconstructed as {} on read
+            this.#writeReflected(buffer, TAG_PLAIN_OBJECT, -1, value);
+            return;
+        }
+
+        throw new Error(`Cannot serialize instance of '${ctor && ctor.name}': it has no registered adapter and no static 'typeName'. Add a static typeName (so it survives minification) or register an adapter.`);
+    }
+
+    /**
+     * Write a reflective object body: `[classIdx] shapeIdx value*`.
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {number} tag {@link TAG_REFLECT_OBJECT} or {@link TAG_PLAIN_OBJECT}
+     * @param {number} classIdx class-table index, or -1 for a plain object (not written)
+     * @param {Object} value
+     */
+    #writeReflected(buffer, tag, classIdx, value) {
+        const names = Object.keys(value);
+        const shapeIdx = this.#internShape(names);
+
+        buffer.writeUint8(tag);
+
+        if (classIdx >= 0) {
+            buffer.writeUintVar(classIdx);
+        }
+
+        buffer.writeUintVar(shapeIdx);
+
+        for (let i = 0; i < names.length; i++) {
+            this.writeValue(buffer, value[names[i]]);
+        }
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+BinaryObjectSerializer.prototype.isBinaryObjectSerializer = true;

package/src/engine/ecs/storage/binary/object-v2/DESIGN.md

@@ -0,0 +1,199 @@
+# Object-graph binary serialization — design
+
+## 1. Purpose
+
+A **general-purpose** binary serializer for arbitrary JavaScript object graphs, layered on the existing
+[`BinaryClassSerializationAdapter`](../BinaryClassSerializationAdapter.js) / upgrader / registry machinery.
+
+The defining goal — and the thing an earlier draft got wrong — is that you can serialize an object of class `X`
+**without hand-writing an adapter for it**. Classes are serialized by reflection over their own fields by default; a
+hand-written adapter is an *optional override* for classes that want a compact or custom encoding.
+
+What it does:
+
+- **Reflection by default.** Plain objects and class instances are serialized field-by-field with no per-class setup.
+- **Adapters as an override.** If a class has an adapter registered in the [`BinarySerializationRegistry`](../BinarySerializationRegistry.js),
+  that adapter owns the encoding (compact, custom, versioned). Reflection is the fallback, not the only path.
+- **Reference semantics.** Shared references are preserved as one instance, and cycles are handled — objects are
+  tracked by identity and re-encoded as back-references.
+- **Compact framing.** Class names and reflective field-name sets ("shapes") are interned into two tables written
+  ahead of the body and referenced by a small integer, so a thousand same-class objects pay for the name once.
+- **Versioning + bidirectional migration.** Adapter-backed classes carry a version; on read, a mismatch is migrated
+  through the registered [`BinaryClassUpgrader`](../BinaryClassUpgrader.js) chain in *either* direction.
+- **Minification-safe identity.** A class is identified by its adapter registration or its static `typeName`, never by
+  the minifier-mangled `constructor.name`.
+
+## 2. Where it sits
+
+```
+BinaryBuffer                         byte stream
+  └─ BinaryClassSerializationAdapter  per-class hand-written serialize/deserialize   (optional override)
+  └─ BinarySerializationRegistry      typeName → adapter, migrator graph, class → typeName
+  └─ ModuleRegistry                   typeName → class            (for reflective reconstruction)
+       └─ BinaryObjectSerializer / BinaryObjectDeSerializer   ← THIS: reflection + adapters + references + tables
+```
+
+This complements the existing storage layer rather than duplicating it. [`BinaryBufferSerializer`](../../BinaryBufferSerializer.js)
+serializes an ECS dataset as *homogeneous collections of components* (one class name per collection, delegating nested
+objects to the older adapter-only `object/BinaryObjectSerializationAdapter`). This system is the general graph tool it
+was missing: heterogeneous graphs, adapter-less classes, and shared/cyclic references. It could serve as a drop-in for
+that nested-object role; that integration is deliberately out of scope here.
+
+## 3. Wire format
+
+```
+DOCUMENT   := HEADER CLASS_TABLE SHAPE_TABLE BODY
+
+HEADER     := u16(OBJECT_MAGIC=0x4F33) u8(OBJECT_FORMAT_VERSION=1)
+
+CLASS_TABLE := uvar(count) record*           record := utf8(typeName) uvar(version)
+SHAPE_TABLE := uvar(count) shape*            shape  := uvar(fieldCount) utf8(name)*
+
+BODY       := VALUE
+
+VALUE      := u8(TAG_NULL) | u8(TAG_UNDEFINED) | u8(TAG_FALSE) | u8(TAG_TRUE)
+            | u8(TAG_POS_INT) uvar(n)             // n >= 0, fits a varint
+            | u8(TAG_NEG_INT) uvar(-n)            // n < 0,  fits a varint
+            | u8(TAG_FLOAT)   float64             // any other number (float, NaN, ±Infinity, huge int)
+            | u8(TAG_STRING)  utf8
+            | u8(TAG_BIGINT)  utf8(decimal)
+            | u8(TAG_REF)     uvar(objectIndex)   // back-reference to an already-seen object/array
+            | u8(TAG_ARRAY)         uvar(length) VALUE*
+            | u8(TAG_PLAIN_OBJECT)  uvar(shapeIdx) VALUE*        // reconstructed as {}
+            | u8(TAG_REFLECT_OBJECT) uvar(classIdx) uvar(shapeIdx) VALUE*   // new Klass() + field assignment
+            | u8(TAG_ADAPTER_OBJECT) uvar(classIdx) <adapter payload>
+```
+
+**Object indices.** Every `ARRAY`, `PLAIN_OBJECT`, `REFLECT_OBJECT` and `ADAPTER_OBJECT` is assigned an index in
+first-seen order — the writer keeps an identity `Map`, the reader an array. Indices are *not written* for new objects
+(both sides count in lock-step); only `TAG_REF` carries an explicit index. Both sides register an object **before**
+reading/writing its contents, so a cyclic child resolves to the (partially built) parent.
+
+**Two version numbers.** `OBJECT_FORMAT_VERSION` versions the framing; the per-class `version` in the class table
+versions one class's payload and drives migration. They never interfere.
+
+**Prepended tables.** The body is built into a scratch buffer while the class/shape tables fill; the document then
+writes header + tables + a byte-copy of the body. Reading is a single forward pass (the tables come first). The only
+cost over single-pass writing is that final copy — as intended.
+
+## 4. Reflection
+
+A class instance with no adapter, or a plain object, is written by enumerating `Object.keys(value)` (own enumerable
+string keys, in insertion order). The ordered name list is interned into the shape table; the body carries the shape
+index and one `VALUE` per field. This *reads* the instance's fields but never mutates it, and assumes no special field
+names — it serializes whatever is there.
+
+On read:
+- `PLAIN_OBJECT` → `{}`, fields assigned.
+- `REFLECT_OBJECT` → `new Klass()` (from the module registry, or the adapter's `klass` if one happens to be
+  registered), fields assigned over it.
+
+Because the shape is self-describing, reflective encoding is naturally tolerant of additive field changes: a reader
+simply materialises whatever fields the shape lists. Semantic changes that need real migration are a reason to graduate
+the class to an adapter.
+
+**Strings and keys are NUL-safe.** All strings this system writes itself — type names, field names, string values and
+bigints — use a byte-length-prefixed UTF-8 codec ([`objectStringCodec.js`](./objectStringCodec.js)), not
+`BinaryBuffer.writeUTF8String`. The latter is NUL-*terminated* on read, so it cannot round-trip a string (or object
+key) containing `U+0000`; the byte-length prefix has no terminator and round-trips every code point. (Strings an
+*adapter* writes with `buffer.writeUTF8String` still follow that primitive's own behaviour — another reason adapters
+own their encoding.)
+
+## 5. Adapters (the override)
+
+When the writer's registry has an adapter for a value's class, the value is written as `ADAPTER_OBJECT`: a class-table
+index plus the adapter's own payload. The adapter fully controls the bytes (e.g. three `float64`s for a `Vector3`,
+skipping field names and per-value tags), and can recurse into arbitrary children through the driving context via
+`this.context.writeValue` / `readValue` (see [`ObjectSerializationAdapter`](./ObjectSerializationAdapter.js)). Adapter
+objects participate in the same reference table, so shared/cyclic adapter instances work too.
+
+Adapters are the extension point for anything reflection shouldn't own: `Vector3`, typed arrays, `Map`/`Set`/`Date`,
+quantised or bit-packed encodings, or classes needing explicit migration.
+
+## 6. Reference semantics
+
+Objects and arrays are tracked by **identity**. The first time an instance is seen it is encoded in full and assigned
+the next index; every later occurrence — whether a shared child or a cycle back to an ancestor — is a `TAG_REF` to that
+index. This preserves object identity across the graph (`restored.a === restored.b`) and makes cyclic graphs
+serialisable instead of stack-overflowing. Primitives are never reference-tracked.
+
+## 7. Versioning & migration
+
+Adapter classes store their `version` once per class in the table. On read, the deserializer resolves migration
+**lazily, on the first `ADAPTER_OBJECT` of the class** — never at class-table time — because whether a class was written
+via an adapter (and so whether the version means anything) is a property of the body tag, not of the reader's registry.
+If the stored version differs from the reader's adapter version (in *either* direction), the payload is run through the
+shortest [`BinaryClassUpgrader`](../BinaryClassUpgrader.js) chain the registry can find. The chain is really a
+*migrator*: it can move down a version as readily as up, so there is no artificial "data must not be newer" rule — only
+"a path must exist".
+
+Reflective classes are stored at version 0 and are never migrated (their shapes already make them additively tolerant).
+
+**Nesting caveat.** A migrator reads one object's payload and rewrites it; the fresh scratch buffers make this
+re-entrant. As with the existing collection path, migrating an *adapter class whose payload itself nests other objects*
+requires the migrator to reproduce that nested framing — rare, and a reason to migrate leaf classes or use reflection.
+
+## 8. Class identity & minification
+
+The name written for a class is resolved, in order:
+1. the name its adapter is registered under (`registry.getClassName(constructor)` — a reverse index keyed on the
+   constructor object, so it survives minification), else
+2. the class's static `typeName` (the deliberate escape hatch: a minifier mangles `constructor.name` but leaves a
+   `static typeName = "Foo"` string intact).
+
+A class instance with neither an adapter nor a `typeName` cannot be safely round-tripped and is rejected at write time
+with a message pointing at the fix. Plain objects (prototype `Object.prototype` or null) need no name — they round-trip
+as `{}`.
+
+## 9. Registries
+
+- **Serializer** needs only a `BinarySerializationRegistry` (adapters + `getClassName` + versions).
+- **Deserializer** needs the same registry plus a `ModuleRegistry` (`typeName → class`) to reconstruct reflective
+  class instances. The module registry is optional when the data has no reflective class instances (plain objects,
+  arrays and adapter-backed classes don't need it). A reflective class missing from it is a clear read-time error.
+
+## 10. Non-goals & limitations
+
+- **Not self-contained for exotic built-ins.** `Date`, `Map`, `Set`, `RegExp`, typed arrays and `ArrayBuffer` are not
+  handled natively — register an adapter for them. This keeps the core small; the adapter mechanism is the seam.
+- **Functions and symbols** cannot be serialized (thrown at write). Symbol-keyed and non-enumerable properties are
+  ignored (`Object.keys` semantics), matching JSON expectations.
+- **Reconstruction uses `new Klass()`** — classes need a usable no-argument constructor. Null-prototype objects come
+  back as ordinary `{}`.
+- **Depth, not breadth, is the limit.** References make cyclic/shared graphs safe, but a pathologically deep graph can
+  still exhaust the call stack.
+
+## 11. Security posture
+
+Deserialization only ever constructs (a) classes with a registered adapter, or (b) classes present in the module
+registry, or (c) plain objects/arrays. It never instantiates an attacker-named arbitrary type and never invokes
+stream-driven methods beyond a class's own `deserialize`. This registry/module allow-list is the standard mitigation
+for the reflective-deserializer RCE lineage (Java `Serializable`, `pickle`, .NET `BinaryFormatter`). Reflection does
+read *all* own-enumerable fields of the objects you hand it — use an adapter when a class must control or withhold
+fields.
+
+## 12. API
+
+`BinaryObjectSerializer(registry)` — `serialize(buffer, value)`, `writeValue(buffer, value)` (for nesting adapters).
+
+`BinaryObjectDeSerializer(registry, modules?)` — `deserialize(buffer)`, `readValue(buffer)` (for nesting adapters),
+`setModuleRegistry(modules)`.
+
+`ObjectSerializationAdapter extends BinaryClassSerializationAdapter` — base for nesting adapters; `initialize(context)`
+captures the serializer/deserializer into `this.context`.
+
+`BinarySerializationRegistry.getClassName(klass)` — reverse of `registerAdapter`; constructor → registered name.
+
+## 13. Tests
+
+- `*.reflection.spec.js` — primitives (incl. bigint, NaN/±Infinity, large-int→float), plain objects, arrays, reflective
+  class instances, nesting, field-order preservation, no-mutation.
+- `*.references.spec.js` — shared references, self-cycles, mutual cycles, self-containing arrays, cycles through class
+  instances and container adapters.
+- `*.adapters.spec.js` — adapter used & respected, adapter framing vs reflective, adapter objects nested/shared,
+  container adapter recursing through the context.
+- `*.versioning.spec.js` — forward migration, **backward** migration, version-match no-op, missing-path error, shared
+  class-table migration.
+- `*.errors.spec.js` — function/symbol rejection, missing typeName, missing module registry, bad magic / format
+  version, `typeName`-as-identity, class+shape interning, large homogeneous collection.
+- `BinarySerializationRegistry.spec.js` — `getClassName` reverse-lookup.

package/src/engine/ecs/storage/binary/object-v2/ObjectBinaryFormat.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared wire-format constants for the general object-graph binary serializer.
+ *
+ * A document is: `HEADER CLASS_TABLE SHAPE_TABLE BODY`, where BODY is a single self-describing VALUE. Every
+ * object/array in the body is assigned an implicit index in first-seen order so later occurrences of the same
+ * instance (shared references, cycles) encode as a compact back-reference. Class names and reflective field-name
+ * sets ("shapes") are interned into the two prepended tables and referenced by index, so a graph of a thousand
+ * same-class objects pays for the class name and field names exactly once.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Magic marker at the head of a document (`'O','3'`). Lets a reader reject a foreign/corrupt stream.
+ * @readonly
+ * @type {number}
+ */
+export const OBJECT_MAGIC: number;
+/**
+ * Version of the framing (header + tables + value tags). Independent of any individual class's payload version.
+ * @readonly
+ * @type {number}
+ */
+export const OBJECT_FORMAT_VERSION: number;
+/** `null`. @readonly @type {number} */
+export const TAG_NULL: number;
+/** `undefined`. @readonly @type {number} */
+export const TAG_UNDEFINED: number;
+/** boolean `false`. @readonly @type {number} */
+export const TAG_FALSE: number;
+/** boolean `true`. @readonly @type {number} */
+export const TAG_TRUE: number;
+/** non-negative integer that fits a varint; followed by `uvar(value)`. @readonly @type {number} */
+export const TAG_POS_INT: number;
+/** negative integer that fits a varint; followed by `uvar(-value)`. @readonly @type {number} */
+export const TAG_NEG_INT: number;
+/** any other number (float, NaN, Infinity, out-of-range integer); followed by `float64`. @readonly @type {number} */
+export const TAG_FLOAT: number;
+/** string; followed by a length-prefixed UTF-8 string. @readonly @type {number} */
+export const TAG_STRING: number;
+/** bigint; followed by its base-10 string form. @readonly @type {number} */
+export const TAG_BIGINT: number;
+/** back-reference to an already-seen object/array; followed by `uvar(objectIndex)`. @readonly @type {number} */
+export const TAG_REF: number;
+/** array; followed by `uvar(length)` then `length` VALUEs. @readonly @type {number} */
+export const TAG_ARRAY: number;
+/** plain object (reconstructed as `{}`); followed by `uvar(shapeIndex)` then one VALUE per field. @readonly @type {number} */
+export const TAG_PLAIN_OBJECT: number;
+/** reflective class instance; followed by `uvar(classIndex) uvar(shapeIndex)` then one VALUE per field. @readonly @type {number} */
+export const TAG_REFLECT_OBJECT: number;
+/** class instance serialized by a registered adapter; followed by `uvar(classIndex)` then the adapter payload. @readonly @type {number} */
+export const TAG_ADAPTER_OBJECT: number;
+//# sourceMappingURL=ObjectBinaryFormat.d.ts.map

package/src/engine/ecs/storage/binary/object-v2/ObjectBinaryFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectBinaryFormat.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/ecs/storage/binary/object-v2/ObjectBinaryFormat.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;GAIG;AACH,2BAFU,MAAM,CAEmB;AAEnC;;;;GAIG;AACH,oCAFU,MAAM,CAEuB;AAIvC,uCAAuC;AACvC,uBAD6B,MAAM,CACT;AAC1B,4CAA4C;AAC5C,4BADkC,MAAM,CACT;AAC/B,gDAAgD;AAChD,wBADsC,MAAM,CACjB;AAC3B,+CAA+C;AAC/C,uBADqC,MAAM,CACjB;AAC1B,mGAAmG;AACnG,0BADyF,MAAM,CAClE;AAC7B,gGAAgG;AAChG,0BADsF,MAAM,CAC/D;AAC7B,qHAAqH;AACrH,wBAD2G,MAAM,CACtF;AAC3B,mFAAmF;AACnF,yBADyE,MAAM,CACnD;AAC5B,4EAA4E;AAC5E,yBADkE,MAAM,CAC5C;AAC5B,gHAAgH;AAChH,sBADsG,MAAM,CACnF;AACzB,uFAAuF;AACvF,wBAD6E,MAAM,CACvD;AAC5B,8HAA8H;AAC9H,+BADoH,MAAM,CACvF;AACnC,oIAAoI;AACpI,iCAD0H,MAAM,CAC3F;AACrC,2IAA2I;AAC3I,iCADiI,MAAM,CAClG"}

package/src/engine/ecs/storage/binary/object-v2/ObjectBinaryFormat.js

@@ -0,0 +1,57 @@
+/**
+ * Shared wire-format constants for the general object-graph binary serializer.
+ *
+ * A document is: `HEADER CLASS_TABLE SHAPE_TABLE BODY`, where BODY is a single self-describing VALUE. Every
+ * object/array in the body is assigned an implicit index in first-seen order so later occurrences of the same
+ * instance (shared references, cycles) encode as a compact back-reference. Class names and reflective field-name
+ * sets ("shapes") are interned into the two prepended tables and referenced by index, so a graph of a thousand
+ * same-class objects pays for the class name and field names exactly once.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Magic marker at the head of a document (`'O','3'`). Lets a reader reject a foreign/corrupt stream.
+ * @readonly
+ * @type {number}
+ */
+export const OBJECT_MAGIC = 0x4F33;
+
+/**
+ * Version of the framing (header + tables + value tags). Independent of any individual class's payload version.
+ * @readonly
+ * @type {number}
+ */
+export const OBJECT_FORMAT_VERSION = 1;
+
+// --- value tags (one byte, first byte of every VALUE) ---
+
+/** `null`. @readonly @type {number} */
+export const TAG_NULL = 0;
+/** `undefined`. @readonly @type {number} */
+export const TAG_UNDEFINED = 1;
+/** boolean `false`. @readonly @type {number} */
+export const TAG_FALSE = 2;
+/** boolean `true`. @readonly @type {number} */
+export const TAG_TRUE = 3;
+/** non-negative integer that fits a varint; followed by `uvar(value)`. @readonly @type {number} */
+export const TAG_POS_INT = 4;
+/** negative integer that fits a varint; followed by `uvar(-value)`. @readonly @type {number} */
+export const TAG_NEG_INT = 5;
+/** any other number (float, NaN, Infinity, out-of-range integer); followed by `float64`. @readonly @type {number} */
+export const TAG_FLOAT = 6;
+/** string; followed by a length-prefixed UTF-8 string. @readonly @type {number} */
+export const TAG_STRING = 7;
+/** bigint; followed by its base-10 string form. @readonly @type {number} */
+export const TAG_BIGINT = 8;
+/** back-reference to an already-seen object/array; followed by `uvar(objectIndex)`. @readonly @type {number} */
+export const TAG_REF = 9;
+/** array; followed by `uvar(length)` then `length` VALUEs. @readonly @type {number} */
+export const TAG_ARRAY = 10;
+/** plain object (reconstructed as `{}`); followed by `uvar(shapeIndex)` then one VALUE per field. @readonly @type {number} */
+export const TAG_PLAIN_OBJECT = 11;
+/** reflective class instance; followed by `uvar(classIndex) uvar(shapeIndex)` then one VALUE per field. @readonly @type {number} */
+export const TAG_REFLECT_OBJECT = 12;
+/** class instance serialized by a registered adapter; followed by `uvar(classIndex)` then the adapter payload. @readonly @type {number} */
+export const TAG_ADAPTER_OBJECT = 13;