@woosh/meep-engine 3.60.4 → 3.60.6

package/src/engine/ecs/storage/binary/SERIALIZATION_COVERAGE.md

@@ -1,272 +0,0 @@
-# Binary serialization coverage
-
-What verifies the save format, what does not, and what is known to be wrong with it.
-
-This file exists because three aggregate specs that used to answer those questions were deleted. They are
-worth understanding before adding anything like them back.
-
-## Why the aggregate harnesses went
-
-`binary_adapter_round_trip.spec.js`, `upgrader_chain_contract.spec.js` and
-`upgrader_execution_contract.spec.js` walked the source tree with `fs.readdirSync`, dynamically imported every
-match, and drove each adapter through reflection.
-
-They found real defects — that was never in doubt. They were removed anyway, for reasons that are worth
-keeping:
-
-* **40% of the green was hollow.** The round-trip harness reported 78 passing tests. **31 of them asserted
-  nothing:** 20 "not checked" (16 of those because the harness's own perturbation produced an object that
-  violated the component's invariants and `serialize` threw — *"Expected 'Managed' flag to be set"*,
-  *"Incorrect height data size. 4 !== 256"*), 4 whose state is `#private` and therefore invisible to
-  structural comparison, and 7 the perturber could not vary. `Tag`, `Blackboard`, `UUID`, `Terrain`,
-  `FogOfWar`, `AudioEmitter`, `SoundEmitter`, `ParticleEmitter` and `AnimationGraph` were all reported green
-  and none of them were checked. The list was printed by `console.log` in an `afterAll`, invisible in a normal
-  run.
-* **It asserted that the broken things were exactly the broken things.** `KNOWN_DIVERGENCE` was, in its own
-  words, "a baseline, not a specification" — nine real defects encoded as expected values. A test that passes
-  *because* the bug is still present is worse than no test.
-* **It hid a bug of exactly the kind it existed to catch.** See "Found and fixed" below.
-* **The reflection was the failure surface.** `perturb()` and `divergentPaths()` were ~250 lines of
-  special-cased traversal (`isColor`, `isQuaternion`, typed arrays, `getValue`/`set`, `__validSet`,
-  writability probing, depth limits, `Math.fround` tolerance). Whenever a test failed, the first question was
-  whether the harness or the adapter was wrong.
-* **The dynamic imports flaked.** On Windows the transform cache lost `rename` races —
-  `EPERM: operation not permitted, rename ...\ssr\.tmp-... -> ...\ssr\<hash>` — failing whichever adapter
-  happened to be importing. The flake was read as a serialization bug more than once.
-
-The replacement is one hand-written spec per adapter, colocated with it, in the style of
-[`TagSerializationAdapter.spec.js`](../../components/TagSerializationAdapter.spec.js): construct an instance
-with distinctive values, serialize, deserialize into a fresh one, assert. Explicit, verbose, no reflection, no
-allow-lists, and each one states what the format actually promises.
-
-**The upgrade-path property is not reproduced.** `upgrader_chain_contract.spec.js` checked that every
-historical version could reach the current one. That property matters to a *consumer* of the engine shipping
-saved data, not to the engine, so it belongs in the consumer's suite.
-
-## Found and fixed on the way out
-
-`FailingBehavior` and `SucceedingBehavior` **could not be serialized at all.** Both adapters wrote
-`value.delayTicks` — a constructor parameter that was deprecated and removed from both classes — so
-`writeUintVar(undefined)` threw on *any* instance, and a behaviour tree containing either could not be saved.
-
-The harness reported both green. `perturb()` found no field it knew how to vary, pushed them onto the
-"nothing the harness could vary" list, and returned before ever calling `serialize`.
-
-Both adapters now write nothing, because the classes carry no state. No version bump: since `serialize` always
-threw, no save containing these behaviours can exist, so there is no data to stay compatible with.
-
-## Adapters still without a spec
-
-28 files, of which `BinaryClassSerializationAdapter.js` (the base class) and
-`ObjectBasedClassSerializationAdapter.js` (a helper) are not adapters — so **26 real ones**. Every entry is an
-adapter nothing currently verifies.
-
-Sixteen of these are the ones whose `serialize` threw under the old harness. That is not a coincidence and it
-is where the interesting bugs are: those components have invariants, so a spec for one needs a hand-built
-fixture rather than a default instance. `FogOfWar` needs correctly-sized height data, `GUIElement` needs its
-`Managed` flag, `Terrain` needs a height array matching its resolution.
-
-| Class | Adapter |
-|---|---|
-| `Animation` | `engine/ecs/animation/AnimationSerializationAdapter.js` |
-| `FogOfWar` | `engine/ecs/fow/serialization/FogOfWarSerializationAdapter.js` |
-| `GUIElement` | `engine/ecs/gui/GUIElementSerializationAdapter.js` |
-| `Book` | `engine/ecs/storage/binary/BinaryClassSerializationAdapter.js` |
-| `?` | `engine/ecs/storage/binary/object/ObjectBasedClassSerializationAdapter.js` |
-| `Terrain` | `engine/ecs/terrain/serialization/TerrainSerializationAdapter.js` |
-| `AnimationController` | `engine/graphics/ecs/animation/AnimationControllerSerializationAdapter.js` |
-| `AnimationGraph` | `engine/graphics/ecs/animation/animator/graph/AnimationGraphSerializationAdapter.js` |
-| `AnimationGraphDefinition` | `engine/graphics/ecs/animation/animator/graph/definition/serialization/AnimationGraphDefinitionSerializationAdapter.js` |
-| `Camera` | `engine/graphics/ecs/camera/serialization/CameraSerializationAdapter.js` |
-| `TopDownCameraController` | `engine/graphics/ecs/camera/topdown/TopDownCameraControllerSerializationAdapter.js` |
-| `Decal` | `engine/graphics/ecs/decal/v2/DecalSerializationAdapter.js` |
-| `Highlight` | `engine/graphics/ecs/highlight/HighlightSerializationAdapter.js` |
-| `Mesh` | `engine/graphics/ecs/mesh/serialization/MeshSerializationAdapter.js` |
-| `Water` | `engine/graphics/ecs/water/WaterSerializationAdapter.js` |
-| `LightProbeVolume` | `engine/graphics/sh3/lpv/serialization/LightProbeVolumeSerializationAdapter.js` |
-| `Sampler2D` | `engine/graphics/texture/sampler/serialization/Sampler2DSerializationAdapter.js` |
-| `GridPosition2Transform` | `engine/grid/grid2transform/GridPosition2TransformSerializationAdapter.js` |
-| `GridObstacle` | `engine/grid/obstacle/GridObstacleSerializationAdapter.js` |
-| `ParallelBehavior` | `engine/intelligence/behavior/composite/ParallelBehaviorSerializationAdapter.js` |
-| `SequenceBehavior` | `engine/intelligence/behavior/composite/SequenceBehaviorSerializationAdapter.js` |
-| `InvertStatusBehavior` | `engine/intelligence/behavior/decorator/InvertStatusBehaviorSerializationAdapter.js` |
-| `RepeatBehavior` | `engine/intelligence/behavior/decorator/RepeatBehaviorSerializationAdapter.js` |
-| `BehaviorComponent` | `engine/intelligence/behavior/ecs/BehaviorComponentSerializationAdapter.js` |
-| `Transform` | `engine/interpolation/TransformPoseSerializationAdapter.js` |
-| `AcousticProbeField` | `engine/sound/simulation/probe/AcousticProbeFieldSerializationAdapter.js` |
-
-## Upgraders
-
-24 upgraders in the tree. Ten had a hand-written golden — an explicit byte layout in the version the upgrader
-reads — and those goldens are the one genuinely brutalist thing in the deleted files. They are preserved here
-verbatim so porting them to per-upgrader specs is transcription rather than archaeology.
-
-The per-upgrader spec should assert **the restored field values**, not the byte count the deleted harness
-asserted. The byte count was a proxy it used because it had no idea what the values ought to be; a spec that
-names one upgrader does know, and should say so.
-
-Upgraders added since carry that spec from the start. The first was IK's, which wrote a version 0 constraint
-field by field, ran it through the chain the engine registry hands a load, and asserted every restored field;
-it went with the component it upgraded (2026-10-06, a hard break: IK's goals live on bones, which are never
-saved).
-
-### Goldens to port
-
-```js
-const GOLDENS = {
-    "CameraSerializationUpgrader_0_1.js": buffer => {
-        buffer.writeUint8(1);   // autoClip
-        buffer.writeUint8(1);   // active, an ObservedBoolean, one byte
-    },
-
-    "ClingToTerrainSerializationUpgrader_0_1.js": buffer => {
-        buffer.writeUint8(1);   // normalAlign
-    },
-
-    "DecalSerializationUpgrader_0_1.js": buffer => {
-        buffer.writeUTF8String("data/textures/decal/circle1.png");
-        buffer.writeFloat32(0);                                     // priority
-        buffer.writeFloat32Array([1, 1, 1, 1], 0, 4);               // colour
-    },
-
-    "HighlightSerializationUpgrader_0_1.js": buffer => {
-        buffer.writeFloat32(0.25);  // r
-        buffer.writeFloat32(0.5);   // g
-        buffer.writeFloat32(0.75);  // b
-        buffer.writeFloat32(1);     // a
-    },
-
-    "PathSerializationUpgrader_0_1.js": buffer => {
-        buffer.writeUint32(2);  // point count
-
-        for (let i = 0; i < 6; i++) {
-            buffer.writeFloat64(i);
-        }
-    },
-
-    "PathSerializationUpgrader_1_2.js": buffer => {
-        buffer.writeUint8(0);       // interpolation
-        buffer.writeUintVar(0);     // marker index
-        buffer.writeFloat32(0);     // marker offset
-        buffer.writeUintVar(2);     // point count
-
-        for (let i = 0; i < 6; i++) {
-            buffer.writeFloat32(i);
-        }
-    },
-
-    "PathSerializationUpgrader_2_3.js": buffer => {
-        buffer.writeUint8(0);       // interpolation
-        buffer.writeUintVar(2);     // point count
-        buffer.writeUintVar(3);     // elements per point
-
-        for (let i = 0; i < 6; i++) {
-            buffer.writeFloat32(i);
-        }
-    },
-
-    "TagSerializationUpgrader_0_1.js": buffer => {
-        buffer.writeUTF8String("a-tag");
-    },
-
-    "TopDownCameraControllerSerializationUpgrader_0_1.js": buffer => {
-        // target x/y/z, pitch, yaw, distance, distanceMin, distanceMax
-        for (let i = 0; i < 8; i++) {
-            buffer.writeFloat64(i + 1);
-        }
-    },
-
-    "TransformSerializationUpgrader_0_1.js": buffer => {
-        buffer.writeFloat64(1);     // position x
-        buffer.writeFloat64(2);     // position y
-        buffer.writeFloat64(3);     // position z
-
-        buffer.writeUint32(0);      // encoded rotation
-
-        buffer.writeFloat32(1);     // scale x
-        buffer.writeFloat32(2);     // scale y
-        buffer.writeFloat32(3);     // scale z
-    }
-};
-```
-
-### Upgraders with no golden
-
-Thirteen versions of the save format that nothing verifies can still be read. This was already an admitted gap
-in the deleted spec; it is not a new one.
-
-> The two `SoundEmitter` upgraders, its v2 adapter and the `SoundController` adapter now live under
-> `engine/sound/sopra/legacy/` alongside the components they read. Those components are frozen readers with no
-> runtime behaviour: they exist so that pre-`AudioEmitter` saves still deserialize, and are fed to
-> `convertLegacySoundComponents`, which turns them into `AudioEmitter` / `AudioEventTrigger`. They stay
-> registered here for exactly that reason — de-registering them would make old saves unreadable.
-
-```js
-const WITHOUT_GOLDEN = [
-    "FogOfWarSerializationUpdater_0_1.js",
-    "GridPosition2TransformSerializationUpgrader_0_1.js",
-    "GridPositionSerializationUpdater_0_1.js",
-    "PathFollowerSerializationUpgrader_0_1.js",
-    "PathFollowerSerializationUpgrader_1_2.js",
-    "PathFollowerSerializationUpgrader_2_3.js",
-    "PathFollowerSerializationUpgrader_3_4.js",
-    "RigidBodySerializationUpgrader_0_1.js",
-    "SoundEmitterSerializationUpgrader_0_1.js",
-    "SoundEmitterSerializationUpgrader_1_2.js",
-    "TerrainSerializationUpgrader_0_1.js",
-    "TerrainSerializationUpgrader_1_2.js",
-    "WaterSerializationUpgrader_0_1.js"
-];
-```
-
-## Known defects in the format
-
-These came out of `KNOWN_DIVERGENCE`, where they were encoded as expected values so the suite stayed green
-with the bugs in place. They are real: an entity saved with any of these set does not come back the same.
-Preserved here as a defect list, which is what they always were.
-
-Where a spec has since been written for the adapter, the divergence is asserted explicitly *with its reason*,
-so the behaviour is visible at the adapter rather than in a table keyed by file path — see
-`LightSerializationAdapter.spec.js` (packed RGB drops alpha, harmless for a light and stated as such) and
-`WaitForEventBehaviorSerializationAdapter.spec.js` (the event name survives, the wait state does not, which is
-a defect and says so).
-
-```js
-const KNOWN_DIVERGENCE = {
-    // Color.toUint() is documented as RGB-only (uint24) and both adapters use
-    // it, so alpha is dropped by design. Kept visible rather than exempted:
-    // a light has no meaningful alpha, but water's might, and that is a call
-    // for whoever owns the water shader.
-    "engine/graphics/ecs/light/LightSerializationAdapter.js": ["color.a"],
-    "engine/graphics/ecs/water/WaterSerializationAdapter.js": ["color.a", "shoreColor.a"],
-
-    // flag fields dropped wholesale
-    "engine/grid/grid2transform/GridPosition2TransformSerializationAdapter.js": ["flags"],
-    "engine/ecs/transform/TransformSerializationAdapter.js": ["flags"],
-    "engine/graphics/ecs/mesh/serialization/MeshSerializationAdapter.js": ["flags"],
-
-    // a behaviour tree restored mid-run resumes from the wrong child
-    "engine/intelligence/behavior/composite/SequenceBehaviorSerializationAdapter.js": [
-        "__currentBehaviourIndex", "__currentBehaviourState"
-    ],
-    "engine/intelligence/behavior/ecs/BehaviorComponentSerializationAdapter.js": ["__behavior"],
-
-    // the event it is waiting for is dropped, so it waits forever
-    "engine/intelligence/behavior/ecs/WaitForEventBehaviorSerializationAdapter.js": [
-        "detected", "entity", "target"
-    ],
-
-    "engine/sound/simulation/ecs/AcousticVolumeSerializationAdapter.js": ["shape.radius"]
-};
-```
-
-Worth separating when these are worked through:
-
-* **Deliberate and harmless** — `Light.color.a`: `Color.toUint()` is documented RGB-only. A light has no
-  meaningful alpha.
-* **Deliberate and questionable** — `Water.color.a`, `Water.shoreColor.a`: same encoding, but water's alpha
-  might mean something. A call for whoever owns that shader.
-* **Straightforwardly broken** — `flags` dropped wholesale on `Transform`, `Mesh` and
-  `GridPosition2Transform`; `SequenceBehavior` resuming from the wrong child; `BehaviorComponent` losing its
-  behaviour entirely; `WaitForEventBehavior` restored on the wrong side of the event it waits for, so it waits
-  forever; `AcousticVolume` losing its radius.

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

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