@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,199 +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.
+# 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.js

@@ -1,57 +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;
+/**
+ * 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;

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

@@ -1,56 +1,56 @@
-import { BinaryClassSerializationAdapter } from "../BinaryClassSerializationAdapter.js";
-
-/**
- * Convenience base class for a hand-written {@link BinaryClassSerializationAdapter} whose class nests other objects
- * that should be serialized through the object-graph system (so they share its reference de-duplication, class table
- * and shape table).
- *
- * Before every use, the driving context passes itself to {@link initialize}: a {@link BinaryObjectSerializer} while
- * writing, a {@link BinaryObjectDeSerializer} while reading. Both expose `writeValue`/`readValue` respectively, so a
- * subclass recurses with `this.context.writeValue(buffer, child)` / `this.context.readValue(buffer)`.
- *
- * Leaf adapters that only read/write primitives do not need this base class — extend
- * {@link BinaryClassSerializationAdapter} directly and ignore the context.
- *
- * Lifecycle note: the object-graph driver calls {@link initialize} before *every* object it (de)serializes (to
- * re-bind the current context) and never calls `finalize()`. Adapters used on this path must therefore not rely on
- * the once-per-run acquire/`finalize`-release lifecycle that the ECS collection path provides.
- *
- * @example
- *   class InventoryAdapter extends ObjectSerializationAdapter {
- *       klass = Inventory;
- *       version = 0;
- *
- *       serialize(buffer, inventory) {
- *           buffer.writeUintVar(inventory.items.length);
- *           for (const item of inventory.items) {
- *               this.context.writeValue(buffer, item);   // any registered type, plain object, or null
- *           }
- *       }
- *
- *       deserialize(buffer, inventory) {
- *           const n = buffer.readUintVar();
- *           for (let i = 0; i < n; i++) {
- *               inventory.items.push(this.context.readValue(buffer));
- *           }
- *       }
- *   }
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class ObjectSerializationAdapter extends BinaryClassSerializationAdapter {
-
-    /**
-     * The context driving the current (de)serialization, used to recurse into nested values.
-     * @type {BinaryObjectSerializer|BinaryObjectDeSerializer}
-     */
-    context = null;
-
-    /**
-     * @param {BinaryObjectSerializer|BinaryObjectDeSerializer} context
-     */
-    initialize(context) {
-        this.context = context;
-    }
-}
+import { BinaryClassSerializationAdapter } from "../BinaryClassSerializationAdapter.js";
+
+/**
+ * Convenience base class for a hand-written {@link BinaryClassSerializationAdapter} whose class nests other objects
+ * that should be serialized through the object-graph system (so they share its reference de-duplication, class table
+ * and shape table).
+ *
+ * Before every use, the driving context passes itself to {@link initialize}: a {@link BinaryObjectSerializer} while
+ * writing, a {@link BinaryObjectDeSerializer} while reading. Both expose `writeValue`/`readValue` respectively, so a
+ * subclass recurses with `this.context.writeValue(buffer, child)` / `this.context.readValue(buffer)`.
+ *
+ * Leaf adapters that only read/write primitives do not need this base class — extend
+ * {@link BinaryClassSerializationAdapter} directly and ignore the context.
+ *
+ * Lifecycle note: the object-graph driver calls {@link initialize} before *every* object it (de)serializes (to
+ * re-bind the current context) and never calls `finalize()`. Adapters used on this path must therefore not rely on
+ * the once-per-run acquire/`finalize`-release lifecycle that the ECS collection path provides.
+ *
+ * @example
+ *   class InventoryAdapter extends ObjectSerializationAdapter {
+ *       klass = Inventory;
+ *       version = 0;
+ *
+ *       serialize(buffer, inventory) {
+ *           buffer.writeUintVar(inventory.items.length);
+ *           for (const item of inventory.items) {
+ *               this.context.writeValue(buffer, item);   // any registered type, plain object, or null
+ *           }
+ *       }
+ *
+ *       deserialize(buffer, inventory) {
+ *           const n = buffer.readUintVar();
+ *           for (let i = 0; i < n; i++) {
+ *               inventory.items.push(this.context.readValue(buffer));
+ *           }
+ *       }
+ *   }
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ObjectSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    /**
+     * The context driving the current (de)serialization, used to recurse into nested values.
+     * @type {BinaryObjectSerializer|BinaryObjectDeSerializer}
+     */
+    context = null;
+
+    /**
+     * @param {BinaryObjectSerializer|BinaryObjectDeSerializer} context
+     */
+    initialize(context) {
+        this.context = context;
+    }
+}