@woosh/meep-engine 3.1.0 → 3.3.0

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

@@ -1,269 +1,269 @@
-# 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
-
-29 files, of which `BinaryClassSerializationAdapter.js` (the base class) and
-`ObjectBasedClassSerializationAdapter.js` (a helper) are not adapters — so **27 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` |
-| `InverseKinematics` | `engine/ecs/ik/InverseKinematicsSerializationAdapter.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` |
-| `ParameterLookupTable` | `engine/graphics/particles/particular/engine/emitter/serde/ParameterLookupTableSerializationAdapter.js` |
-| `ParticleEmitter` | `engine/graphics/particles/particular/engine/emitter/serde/ParticleEmitterSerializationAdapter.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.
-
-### 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
-
-Fourteen 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.
-
-```js
-const WITHOUT_GOLDEN = [
-    "FogOfWarSerializationUpdater_0_1.js",
-    "GridPosition2TransformSerializationUpgrader_0_1.js",
-    "GridPositionSerializationUpdater_0_1.js",
-    "ParticleEmitterSerializationUpgrader_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"],
-
-    "engine/graphics/particles/particular/engine/emitter/serde/ParameterLookupTableSerializationAdapter.js": [
-        "flags", "valueMax", "valueMin"
-    ],
-
-    // 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.
+# 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
+
+29 files, of which `BinaryClassSerializationAdapter.js` (the base class) and
+`ObjectBasedClassSerializationAdapter.js` (a helper) are not adapters — so **27 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` |
+| `InverseKinematics` | `engine/ecs/ik/InverseKinematicsSerializationAdapter.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` |
+| `ParameterLookupTable` | `engine/graphics/particles/particular/engine/emitter/serde/ParameterLookupTableSerializationAdapter.js` |
+| `ParticleEmitter` | `engine/graphics/particles/particular/engine/emitter/serde/ParticleEmitterSerializationAdapter.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.
+
+### 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
+
+Fourteen 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.
+
+```js
+const WITHOUT_GOLDEN = [
+    "FogOfWarSerializationUpdater_0_1.js",
+    "GridPosition2TransformSerializationUpgrader_0_1.js",
+    "GridPositionSerializationUpdater_0_1.js",
+    "ParticleEmitterSerializationUpgrader_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"],
+
+    "engine/graphics/particles/particular/engine/emitter/serde/ParameterLookupTableSerializationAdapter.js": [
+        "flags", "valueMax", "valueMin"
+    ],
+
+    // 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.