@woosh/meep-engine 2.165.0 → 2.165.1

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;

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

@@ -0,0 +1,53 @@
+/**
+ * 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<any> {
+    constructor();
+    /**
+     * The context driving the current (de)serialization, used to recurse into nested values.
+     * @type {BinaryObjectSerializer|BinaryObjectDeSerializer}
+     */
+    context: BinaryObjectSerializer | BinaryObjectDeSerializer;
+    /**
+     * @param {BinaryObjectSerializer|BinaryObjectDeSerializer} context
+     */
+    initialize(context: BinaryObjectSerializer | BinaryObjectDeSerializer): void;
+}
+import { BinaryClassSerializationAdapter } from "../BinaryClassSerializationAdapter.js";
+//# sourceMappingURL=ObjectSerializationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/ecs/storage/binary/object-v2/ObjectSerializationAdapter.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH;;IAEI;;;OAGG;IACH,SAFU,iDAA+C,CAE1C;IAEf;;OAEG;IACH,oBAFW,iDAA+C,QAIzD;CACJ;gDAvD+C,uCAAuC"}

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

@@ -0,0 +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;
+    }
+}

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

@@ -0,0 +1,110 @@
+# object-v2 — general object-graph binary serialization
+
+Serialize an arbitrary JavaScript object graph to a `BinaryBuffer` and back. Classes are serialized by **reflection by
+default** — no per-class code required — and a hand-written adapter is an optional override for classes that want a
+compact or custom encoding. Shared references and cycles are preserved; class names and field-name sets are interned so
+repeated types are cheap.
+
+See [DESIGN.md](./DESIGN.md) for the wire format and rationale.
+
+## Quick start (reflection — no adapter)
+
+```js
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+import { ModuleRegistry } from "../../../../../core/model/ModuleRegistry.js";
+import { BinarySerializationRegistry } from "../BinarySerializationRegistry.js";
+import { BinaryObjectSerializer } from "./BinaryObjectSerializer.js";
+import { BinaryObjectDeSerializer } from "./BinaryObjectDeSerializer.js";
+
+class Monster {
+    name = "";
+    hp = 0;
+    loot = [];
+}
+Monster.typeName = "Monster";   // stable identity (survives minification)
+
+const registry = new BinarySerializationRegistry();   // no adapter needed
+const modules = new ModuleRegistry();
+modules.add("Monster", Monster);                       // so the reader can reconstruct it
+
+const buffer = new BinaryBuffer();
+new BinaryObjectSerializer(registry).serialize(buffer, someMonster);
+
+buffer.position = 0;
+const restored = new BinaryObjectDeSerializer(registry, modules).deserialize(buffer);
+```
+
+Plain objects and arrays need no registration at all:
+
+```js
+new BinaryObjectSerializer(registry).serialize(buffer, { a: 1, tags: ["x", "y"], nested: { z: true } });
+```
+
+## Custom adapter (the override)
+
+Register a `BinaryClassSerializationAdapter` and it takes over that class's encoding — used automatically wherever the
+class appears in the graph:
+
+```js
+class Vector3Adapter extends BinaryClassSerializationAdapter {
+    klass = Vector3;
+    version = 0;
+    serialize(buffer, v)   { buffer.writeFloat64(v.x); buffer.writeFloat64(v.y); buffer.writeFloat64(v.z); }
+    deserialize(buffer, v) { v.x = buffer.readFloat64(); v.y = buffer.readFloat64(); v.z = buffer.readFloat64(); }
+}
+
+registry.registerAdapter(new Vector3Adapter());   // Vector3 now uses this everywhere
+```
+
+A class that nests other objects extends `ObjectSerializationAdapter` and recurses through `this.context`:
+
+```js
+import { ObjectSerializationAdapter } from "./ObjectSerializationAdapter.js";
+
+class BagAdapter extends ObjectSerializationAdapter {
+    klass = Bag;
+    version = 0;
+    serialize(buffer, bag) {
+        buffer.writeUintVar(bag.items.length);
+        for (const item of bag.items) this.context.writeValue(buffer, item);   // any type, or null
+    }
+    deserialize(buffer, bag) {
+        const n = buffer.readUintVar();
+        for (let i = 0; i < n; i++) bag.items.push(this.context.readValue(buffer));
+    }
+}
+```
+
+## References & cycles
+
+Shared and cyclic references are preserved automatically:
+
+```js
+const shared = { id: 1 };
+const restored = /* round trip */ { a: shared, b: shared };
+restored.a === restored.b;   // true
+
+const node = {}; node.self = node;
+/* round trip */ node.self === node;   // true
+```
+
+## Versioning
+
+Bump an adapter's `version` when its layout changes and register a migrator. Migration runs in **either** direction —
+reading older *or* newer data works as long as a path exists:
+
+```js
+class WidgetMigrator_0_1 extends BinaryClassUpgrader {
+    __startVersion = 0;
+    __targetVersion = 1;
+    upgrade(source, target) { /* read v0 bytes from source, write v1 bytes to target */ }
+}
+registry.registerUpgrader("Widget", new WidgetMigrator_0_1());
+```
+
+## What it does not do
+
+- **No native `Date`/`Map`/`Set`/typed arrays** — register an adapter for them.
+- **No functions or symbols** (serialization throws; symbol/non-enumerable keys are ignored).
+- **Reconstruction uses `new Klass()`** — classes need a no-argument constructor and must be registered (adapter or
+  module registry) so the reader can build them; only registered/plain types are ever instantiated.

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

@@ -0,0 +1,13 @@
+/**
+ * Write a string as `uvar(byteLength)` + raw UTF-8 bytes.
+ * @param {BinaryBuffer} buffer
+ * @param {string} value
+ */
+export function writeObjectString(buffer: BinaryBuffer, value: string): void;
+/**
+ * Read a string written by {@link writeObjectString}.
+ * @param {BinaryBuffer} buffer
+ * @returns {string}
+ */
+export function readObjectString(buffer: BinaryBuffer): string;
+//# sourceMappingURL=objectStringCodec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"objectStringCodec.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/ecs/storage/binary/object-v2/objectStringCodec.js"],"names":[],"mappings":"AAuBA;;;;GAIG;AACH,+DAFW,MAAM,QAOhB;AAED;;;;GAIG;AACH,wDAFa,MAAM,CASlB"}

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

@@ -0,0 +1,48 @@
+/**
+ * NUL-safe string codec for the object-graph serializer.
+ *
+ * The engine's {@link BinaryBuffer.writeUTF8String}/{@link BinaryBuffer.readUTF8String} pair is intentionally
+ * NUL-terminated on read (an in-band `0x00` byte ends the string), so it cannot round-trip strings — or object keys —
+ * that contain `U+0000`. Because this serializer must handle *arbitrary* strings and field names by reflection, it
+ * uses this byte-length-prefixed encoding instead: `uvar(byteLength)` followed by the raw UTF-8 bytes. There is no
+ * terminator, so every code point (including `U+0000`) round-trips, and a following value never desynchronizes.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * @type {TextEncoder}
+ */
+const ENCODER = new TextEncoder();
+
+/**
+ * @type {TextDecoder}
+ */
+const DECODER = new TextDecoder();
+
+/**
+ * Write a string as `uvar(byteLength)` + raw UTF-8 bytes.
+ * @param {BinaryBuffer} buffer
+ * @param {string} value
+ */
+export function writeObjectString(buffer, value) {
+    const bytes = ENCODER.encode(value);
+
+    buffer.writeUintVar(bytes.length);
+    buffer.writeBytes(bytes, 0, bytes.length);
+}
+
+/**
+ * Read a string written by {@link writeObjectString}.
+ * @param {BinaryBuffer} buffer
+ * @returns {string}
+ */
+export function readObjectString(buffer) {
+    const length = buffer.readUintVar();
+
+    const bytes = new Uint8Array(length);
+    buffer.readBytes(bytes, 0, length);
+
+    return DECODER.decode(bytes);
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Serialize `value` with a serializer built on `registry`, then deserialize it with a deserializer built on
+ * `registry` + `modules`. Shared by the object-graph specs.
+ *
+ * @template T
+ * @param {T} value
+ * @param {{registry?: BinarySerializationRegistry, modules?: ModuleRegistry}} [options]
+ * @returns {T}
+ */
+export function roundTrip<T>(value: T, { registry, modules }?: {
+    registry?: BinarySerializationRegistry;
+    modules?: ModuleRegistry;
+}): T;
+/**
+ * @param {*} value
+ * @param {BinarySerializationRegistry} [registry]
+ * @returns {BinaryBuffer} rewound to position 0
+ */
+export function serialize(value: any, registry?: BinarySerializationRegistry): BinaryBuffer;
+/**
+ * @param {*} value
+ * @param {BinarySerializationRegistry} [registry]
+ * @returns {number} byte length of the serialized form
+ */
+export function serializedSize(value: any, registry?: BinarySerializationRegistry): number;
+import { BinarySerializationRegistry } from "../BinarySerializationRegistry.js";
+import { ModuleRegistry } from "../../../../../core/model/ModuleRegistry.js";
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+//# sourceMappingURL=serializerTestHarness.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serializerTestHarness.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/ecs/storage/binary/object-v2/serializerTestHarness.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,+DAHW;IAAC,QAAQ,CAAC,EAAE,2BAA2B,CAAC;IAAC,OAAO,CAAC,EAAE,cAAc,CAAA;CAAC,KAS5E;AAED;;;;GAIG;AACH,iDAHW,2BAA2B,GACzB,YAAY,CAQxB;AAED;;;;GAIG;AACH,sDAHW,2BAA2B,GACzB,MAAM,CAIlB;4CAzC2C,mCAAmC;+BADhD,6CAA6C;6BAD/C,4CAA4C"}