@woosh/meep-engine 3.0.2 → 3.2.0

package/src/DUPLICATION_AUDIT_2026_08_07/G_net_save.md

@@ -1,129 +1,129 @@
-# Domain G — engine/network + engine/save + engine/ecs/storage
-
-Source root for all paths: `H:/git/moh/app/src/mir-engine/meep/src/`.
-Every finding below was verified by opening the cited files. `*.spec.js` and `prototype*/test*` harnesses excluded.
-
-## Findings
-
-| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
-|---|---|---|---|---|---|---|---|
-| 1 | **CRITICAL** | **The ActionLog record wire-format is hand-parsed in 5 independent places** (written in 1). Format is documented only in a comment block, never in code. | writer: `engine/network/sim/SimActionExecutor.js:242-302` `execute`; readers: `engine/network/replication/Replicator.js:335` `#scan_record_in_scope`, `engine/network/replication/Replicator.js:376` `#copy_action_to`, `engine/network/sim/RewindEngine.js:119` `#skip_record`, `engine/network/sim/RewindEngine.js:143` `#restore_prior_state`, `engine/network/orchestrator/ServerAuthoritativeServer.js:502` `#read_historical` | All five readers repeat the identical 8-line prologue: `readUintVar()` prior_count → loop{`readUintVar` entity_id, `readUint8` component_type_id, `readUint32` payload_len, `position += len`} → `readUint8` action_type_id → `readUint8` sender_id → `readUint32` action_payload_len. `Replicator.js:359` and `RewindEngine.js:130` both carry the same `// sender_id` comment. Format spec lives in `engine/network/sim/ActionLog.js:10-22` (a docblock). Changing the payload_len width, adding a field, or reordering requires 6 coordinated edits with zero compile-time coupling; one miss silently misparses every subsequent record in the frame. | `UNJUSTIFIED` | One `engine/network/sim/action_record.js` module: `action_record_write_prior(buffer, ...)`, `action_record_read_header(buffer, out)`, `action_record_skip(buffer)`. Readers 3–5 become 1-line calls; `#restore_prior_state`/`#read_historical` keep only their per-entry payload handling. | Medium effort / Medium risk — hot path, but `sim_action.spec.js`, `RewindEngine.spec.js`, `Replicator.spec.js`, `ServerAuthoritative.spec.js` cover it end-to-end. |
-| 2 | **HIGH** | **`ActionLog` and `InputRing` are the same per-frame ring of `BinaryBuffer` slots**, written twice. | `engine/network/sim/ActionLog.js:39-189` (class `ActionLog`); `engine/network/state/InputRing.js:28-173` (class `InputRing`) | Both hold `#buffers: BinaryBuffer[]`, `#frame_numbers: Int32Array` filled `-1`, `#write_ends: Int32Array`, index by `frame % frame_capacity`. `ActionLog.js:49-95` vs `InputRing.js:37-73` constructors are 97% token-identical (mechanical brief C, sim=0.969) — same validation throw, same three allocations, same `setCapacity` loop. `buffer_for` (`ActionLog.js:165` / `InputRing.js:124`) and `write_end_for` (`ActionLog.js:181` / `InputRing.js:139`) are token-identical. Only the *framing policy* differs: ActionLog has explicit `begin_frame`/`end_frame` (open-frame state), InputRing has a single atomic `write(frame, writer)`. The `has()` vs `has_frame()` naming divergence is pure accident. | `UNJUSTIFIED` | Promote a `FrameBufferRing` to `core/collection/` (or `engine/network/state/`) owning `frame_capacity`, `#buffers`, `#frame_numbers`, `#write_ends`, `has(frame)`, `buffer_for(frame)`, `write_end_for(frame)`, `slot_begin(frame)`, `slot_commit(frame)`. `ActionLog` composes it and adds the open-frame guard; `InputRing` composes it and adds `write`/`for_each_in_range`. Do **not** unify via a sentinel/flag parameter (house rule). | Low effort / Low risk — both classes have direct specs; the extracted primitive is ~70 lines with no behaviour change. |
-| 3 | **HIGH** | **No shared binary codec exists for the engine's own value types; every adapter open-codes `write 3 floats`.** Systemic, not per-file. | `engine/ecs/transform/TransformSerializationAdapter.js:24-26`; `engine/interpolation/TransformPoseSerializationAdapter.js:33-39`; `engine/network/adapters/TransformReplicationAdapter.js:51-53`; `engine/network/adapters/Vector3InterpolationAdapter.js:29-31,42-44`; `engine/physics/ecs/RigidBodySerializationAdapter.js:33,37,43`; `engine/physics/ecs/JointSerializationAdapter.js:30-31`; `engine/graphics/ecs/camera/topdown/TopDownCameraControllerSerializationAdapter.js:16`; `engine/input/devices/gamepad/GamepadStickCalibration.js:101`; `engine/navigation/ecs/components/PathSerializationAdapter.js:30` | Nine files each write `buffer.writeFloatNN(v.x); …(v.y); …(v.z);` inline. `Vector3.toBinaryBuffer` (`core/geom/Vector3.js:1044`) and `toBinaryBufferFloat32` (`:1068`) exist and are marked `@deprecated` — deprecated in favour of *nothing*, so callers regressed to inline code. Meanwhile `core/geom/vec3/serialization/v3_binary_equality_encode.js`/`_decode.js` **is** the shape that works and is reused by exactly 3 adapters (`TransformSerializationAdapter.js:37,52`, `TransformReplicationAdapter.js:62,79`, `TransformInterpolationAdapter.js:37,46,77`) — proof the primitive pattern is viable and already half-built. | `PROMOTION` | Add `core/geom/vec3/serialization/v3_binary_write_f32/_f64` + `v3_binary_read_f32/_f64(buffer, out, offset)`, and `v4_`/`quat3_` siblings next to the existing `v3_binary_equality_*`. Delete the `@deprecated` `Vector*.toBinaryBuffer*` methods' bodies in favour of delegating (they are public library surface — keep the names). | Low effort / Low risk per site; the value is that a precision or endianness change becomes one edit. |
-| 4 | **HIGH** | **AUTH_STATE payload is an untagged concatenation whose writer and reader are two independently-written loops.** A skip on one side silently desynchronizes the whole payload. | writer: `engine/network/NetworkSession.js:1481-1506` `#send_auth_state_for_entity`; reader: `engine/network/NetworkSession.js:1912-1920` `onApplyAuthState` handler | Writer iterates `this.#replicated`, `continue`s when `world.getComponent(entity_id, ComponentClass) === undefined`, and calls `adapter.serialize(buf, live)` — **no per-component tag, no length prefix**. Reader iterates the same map and `continue`s when the *receiver's* `getComponent` is undefined. The two skip predicates evaluate on different worlds. If host and client component composition differ for one entity (common during spawn/despawn races), the reader deserializes component N's bytes into component N+1. The comment at `:1910` ("Mirrors the host's serialize order") is the only thing enforcing the invariant. | `UNJUSTIFIED` | Both loops call one `#for_each_replicated(entity_id, cb)` helper, and the payload gains a `uint8 type_id + uint32 len` frame per component — the same framing `Snapshotter` already uses (`engine/network/sim/Snapshotter.js:82-91`). That makes reader skips independent of writer skips. | Medium effort / Medium risk — wire-format change; `ServerAuthoritative.spec.js` and `NetworkPeer.auth_state.spec.js` are the gate. |
-| 5 | **HIGH** | **Three complete tagged-value object-graph serializers coexist**, two of them with no production consumer. | `engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter.js` (v1, 130 lines); `engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter2.js` (v2, 493 lines); `engine/ecs/storage/binary/object-v2/BinaryObjectSerializer.js` + `BinaryObjectDeSerializer.js` (v3, 331+315 lines) | `BinaryObjectSerializationAdapter2.js:3-14` declares `HEADER_TAG_NULL/UNDEFINED/BOOLEAN_TRUE/BOOLEAN_FALSE/POSITIVE_INTEGER/NEGATIVE_INTEGER/FLOAT/STRING`; `object-v2/ObjectBinaryFormat.js:31-45` declares `TAG_NULL/UNDEFINED/FALSE/TRUE/POS_INT/NEG_INT/FLOAT/STRING` — same eight concepts, different numbering. `Adapter2.#trySerializePrimitive` (`:263-310`) and `BinaryObjectSerializer.writeValue` (`:195-238`) are the same `switch (typeof value)` with the same int/varint-vs-float64 split; `Adapter2.deserialize` (`:442-486`) and `BinaryObjectDeSerializer.readValue` (`:182-227`) the same tag switch. Adapter2 additionally reimplements the shape/schema table (`#writeSchema`/`#readSchema` `:194-255`, class `SchemaTable` `:92-151`) that object-v2 implements as `#internShape`/shape table. **Grep shows `BinaryObjectSerializationAdapter2` has zero importers anywhere in `src/`**, and object-v2 has none outside its own README/DESIGN/specs/`serializerTestHarness.js`. Only v1 is wired (`engine/ecs/storage/BinaryBufferSerializer.js:125`, `BinaryBufferDeSerializer.js:108`, `engine/intelligence/blackboard/BlackboardDynamicStorageAdapter.js:44`, `engine/sound/sopra/serialization/*`). | `UNJUSTIFIED` | object-v2 is strictly the superset (refs/cycles, class table, shape table, bidirectional migration). Delete `BinaryObjectSerializationAdapter2.js` — it is an abandoned intermediate, not library surface anyone can be using (no importers, no spec). Then migrate `BinaryBufferSerializer/DeSerializer` to object-v2 and reduce v1 to a shim, or explicitly document v1 as the ECS-collection path and object-v2 as the graph path. | Deleting Adapter2: trivial. Migrating v1→v3: high effort / high risk (save-file format), and should be a separate decision. |
-| 6 | **HIGH** | **"Resolve the migrator chain for a stored version, or throw" is written 3×, and the three have divergent up/down policies.** | `engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter.js:104-118` `deserialize`; `engine/ecs/storage/binary/collection/BinaryCollectionDeSerializer.js:215-232` `initialize`; `engine/ecs/storage/binary/object-v2/BinaryObjectDeSerializer.js:278-302` `#readAdapterObject` | All three: read stored `version` → compare to `adapter.version` → `registry.getUpgradersChain(name, version, adapter.version)` → throw if `null` → `executeBinaryClassUpgraderChain(chain, buffer, tmp0, tmp1)`. But `BinaryCollectionDeSerializer.js:215` **throws outright** when `version > adapter.version`, whereas `BinaryObjectDeSerializer.js:279` explicitly supports it ("migrate up OR down to the adapter's current version") and v1 (`:108`) just tests `!==`. Same registry, same upgrader graph, three different downgrade policies. Buffer management also diverges: v1 reuses two long-lived `__upgradeBuffer0/1` fields (`:24-30`), object-v2 allocates a fresh pair per object (`:301`), collection resets its pair per `initialize` (`:235-236`). | `UNJUSTIFIED` | One `binary_migrate_payload(registry, typeName, stored_version, adapter, buffer)` in `engine/ecs/storage/binary/`, returning the migrated buffer or the original. Pick one downgrade policy and document it. | Low effort / Medium risk — the behaviour unification is the risky part, not the extraction. |
-| 7 | **MEDIUM** | `NetworkSession.normalize_if_dirty` and `#render_interpolated_entities` share a verbatim 18-line nested traversal. | `engine/network/NetworkSession.js:1063-1082` (inside `normalize_if_dirty`); `engine/network/NetworkSession.js:2003-2023` (inside `#render_interpolated_entities`) | Identical body: `for (const entity_id of this.#remote_entities)` → `getComponent(entity_id, NetworkIdentity)` guard → `for (const [ComponentClass, desc] of this.#replicated)` → `desc.interp === null` guard → live-component guard → `scratch.position = 0` → `#interp_log.interpolate(scratch, identity.network_id, desc.interp_type_id, …)` → `if (!ok) continue` → `scratch.position = 0` → `binary_registry.getAdapter(ComponentClass.typeName).deserialize(scratch, live)`. The only differences are the `(tick, tick, 0)` vs `(tick_a, tick_b, t)` arguments and a `wrote_anything = true` line. The same outer traversal appears a third time (serializing, not deserializing) at `:1947-1959` `#on_frame_applied`. | `UNJUSTIFIED` | Extract `#apply_interpolated(tick_a, tick_b, t) → boolean`. `normalize_if_dirty` calls it with `(tick, tick, 0)`; `#render_interpolated_entities` calls it with the computed triple and uses the return for `render_dirty`. Extract `#for_each_remote_replicated(cb)` for the shared outer walk so `#on_frame_applied` uses it too. | Low effort / Low risk. |
-| 8 | **MEDIUM** | Transport adapters copy-paste their entire stats and disconnect-latch machinery instead of putting it on the `Transport` base. | `getStats()` ×6: `engine/network/transport/LoopbackTransport.js:186`, `engine/network/transport/adapters/SimulatedTransport.js:244`, `.../WebRTCDataChannelTransport.js:123`, `.../WebSocketTransport.js:172`, `.../NodeUDPTransport.js:198`, `.../WebTransportTransport.js:161`. Latch: `WebSocketTransport.js:61,89-90,159`, `WebRTCDataChannelTransport.js:49,63-64,70-71,109`, `NodeUDPTransport.js:59,81-82,88-89,168,184`. Base class: `engine/network/transport/Transport.js:29-112` | All six `getStats()` bodies are the identical 6-line field-by-field copy of a `{bytes_in, bytes_out, packets_in, packets_out}` object; all six declare `#stats = { bytes_in: 0, … }`. Three adapters independently implement the "`#disconnect_fired` latch so a local `disconnect()` doesn't echo `onDisconnect`" idiom, each with its own copy of `if (this.#disconnect_fired) return; this.#disconnect_fired = true; this.onDisconnect.send1(reason);`. **`WebTransportTransport` has no latch at all** (`:146-156` `disconnect()`), so it *does* echo — the divergence a shared base would have prevented. `disconnect()` is token-identical (65 tokens) between `SimulatedTransport.js:228` and `LoopbackTransport.js:166` (mechanical brief A). `send()` is token-identical (64 tokens) between `WebRTCDataChannelTransport.js:87` and `WebSocketTransport.js:103`; `NodeUDPTransport.js:131` is the same plus a remote-null check — all three compute `const payload = (length === bytes.byteLength) ? bytes : bytes.subarray(0, length)`. | `UNJUSTIFIED` | Move `#stats` + `getStats()` + protected `count_in(n)`/`count_out(n)` onto `Transport`. Add a protected `fire_disconnect_once(reason)` + `latch_disconnect()` pair there. Add a `transport_trim_payload(bytes, length)` helper (or accept the 1-liner). Leave the paired `disconnect()` of Loopback/Simulated as-is unless the pair-unbinding is hoisted to a shared `PairedTransport` base. | Low effort / Low risk — `Transport.js` already exists precisely as the shared base and is under-used. |
-| 9 | **MEDIUM** | `send_fragmented` and `resend_fragment_chunk` duplicate the fragment header write, the chunk-slice math, and — with two *different formulas* — the `total_chunks` derivation. | `engine/network/transport/fragments/fragment_send.js:69-86` (`send_fragmented` loop body); `engine/network/transport/fragments/fragment_send.js:127-146` (`resend_fragment_chunk`) | Both compute `chunk_offset = i * MAX_FRAGMENT_CHUNK_BYTES`, `remaining`, `chunk_size = remaining < MAX ? remaining : MAX`, then write the identical 5-byte header (`scratch[0]=type; scratch[1]=id&0xFF; scratch[2]=(id>>8)&0xFF; scratch[3]=index; scratch[4]=total`), `scratch.set(payload.subarray(...), FRAGMENT_HEADER_BYTES)`, `send_fn(scratch, FRAGMENT_HEADER_BYTES + chunk_size)`. `total_chunks` is `Math.ceil(len/MAX)` at `:61` but `len <= MAX ? 1 : Math.ceil(len/MAX)` at `:127-129`. The doc at `:96-97` states the invariant ("The wire layout matches what `send_fragmented` would have produced") in prose because nothing enforces it — and a retransmitted chunk that carries a different `total_chunks` than the original makes the receiver drop the whole assembly (`FragmentAssembler.js:168-173`). | `UNJUSTIFIED` | One module-private `write_fragment_chunk(payload, payload_length, message_id, chunk_index, total_chunks, type, scratch, send_fn)` and one `fragment_total_chunks(payload_length)`. Both exports become thin loops/guards over it. | Low effort / Low risk — `fragment_send` has a spec and the NACK path has `NetworkPeer` integration coverage. |
-| 10 | **MEDIUM** | `ServerAuthoritativeServer` compacts its 4 parallel pending arrays with two near-verbatim 19-line methods differing only in an inequality. | `engine/network/orchestrator/ServerAuthoritativeServer.js:597-616` `#pending_trim_to_window`; `engine/network/orchestrator/ServerAuthoritativeServer.js:634-653` `#pending_filter_to_future` | Byte-for-byte identical apart from `>= window_oldest` vs `> keep_threshold`: same `kept` cursor, same four `[kept] = [i]` assignments, same four `.length = kept` truncations, same `#pending_referenced_frames.length = 0` + rebuild loop. The code says so itself at `:629-631`: *"Same structural pattern as `__pending_trim_to_window` but with the inequality flipped"*. Adding a fifth parallel array means editing both. | `UNJUSTIFIED` | Single `#pending_keep_from(min_frame)` — callers pass `window_oldest` and `keep_threshold + 1`. Uniform control flow, no predicate parameter, no sentinel. | Trivial effort / Low risk — `ServerAuthoritative.spec.js` covers both paths. |
-| 11 | **MEDIUM** | `snapshotter_apply` and `snapshotter_apply_to_existing` are two hand-written parsers of one wire format, with divergent bounds handling. | `engine/network/sim/Snapshotter.js:108-151` `snapshotter_apply`; `engine/network/sim/Snapshotter.js:176-222` `snapshotter_apply_to_existing` | Same outer/inner loop, same three `MalformedPacketError` bounds checks (entity overrun, payload overrun, read-past-end) with only the function name changed in the message, same `type_id/payload_len` read, same skip-to-stay-aligned pattern. They differ only in what happens per component: create-entity-and-attach vs look-up-and-deserialize-in-place (three skip cases at `:200-213` vs one at `:134-138`). A future hardening of the length validation must be applied twice. | `UNJUSTIFIED` | One `snapshotter_walk(buffer, buffer_end, on_entity, on_component)` doing the framing + all bounds checks; the two public functions supply the two apply policies. | Low effort / Low risk — `Snapshotter.spec.js` has dedicated malformed-packet tests (`:338`, `:369`). |
-| 12 | **MEDIUM** | `NetworkPeer` repeats the same 6-line send prologue/epilogue across 9 packet-send methods. | `engine/network/orchestrator/NetworkPeer.js` — `send_recovery_request:947`, `send_state_burst_for_range:975`, `send_auth_state:1038`, `send_initial_sync:1064`, `send_resume_hello:1089`, `send_resume_accept:1110`, `send_resume_reject:1125`, `send_disconnect:1144`, `send_time_dilation_feedback:1168` | Each is: `const conn = this.#peers.get(peer_id); if (conn === undefined) throw new Error(\`NetworkPeer.<name>: peer ${peer_id} not connected\`); this.#send_buffer.position = 0; this.#send_buffer.writeUint8(NetworkPacketType.<X>);` … `this.#send_to_peer(conn, this.#send_buffer.raw_bytes, this.#send_buffer.position);` — 9 copies of the connection lookup + error string + buffer reset + type byte + dispatch. This is duplicated *logic* (lookup/throw/reset), not adapter shape. | `UNJUSTIFIED` | Private `#begin_packet(peer_id, method_name, packet_type) → conn` and `#end_packet(conn)`. Each `send_*` keeps only its own field writes. Stays fully typed — no string-keyed dispatch table. | Trivial effort / Low risk. |
-| 13 | **MEDIUM** | The security-critical bounds-checked action-header read is written 3× inside a single method. | `engine/network/replication/Replicator.js:224-231` (deferral path), `:256-263` (skip path), `:272-279` (apply path) | Each block is `if (in_buffer.position + ACTION_HEADER_BYTES > in_buffer_end) throw new MalformedPacketError(...); readUint8(); const len = readUint32(); if (in_buffer.position + len > in_buffer_end) throw new MalformedPacketError(...)`. Three copies of the invariant that gates untrusted-length parsing (comment at `:219-223` explains why it must not be an `assert`). The three error messages have already drifted ("action header overruns packet" vs "…(skip; frame …)" vs "skipped action payload of …"). One missed copy = OOB read / cross-packet leak. | `UNJUSTIFIED` | `#read_action_header(buffer, end, frame, i, count) → payload_len` (or a small `{type_id, payload_len}` out-param object hoisted to a field to avoid allocation). All three call it. | Trivial effort / Low risk — `Replicator.spec.js:644,666` already test malformed lengths. |
-| 14 | **MEDIUM / PROMOTION** | Shortest-path quaternion nlerp (dot-sign-flip → componentwise lerp → normalize) written 3× with no core primitive. | `engine/network/adapters/QuaternionInterpolationAdapter.js:27-42`; `engine/network/adapters/TransformInterpolationAdapter.js:56-65`; a third variant (lerp toward identity) at `engine/network/sim/SmoothingState.js:166-183` | The first two are the same 12 lines: `if (a·b < 0) negate b`, four `q = a + (b - a) * t`, `len2`, `inv_len = len2 > 0 ? 1/Math.sqrt(len2) : 1`, scale. `core/geom/3d/quaternion/` has `quat3_multiply`, `quat3_integrate`, `quat3_from_axis_angle`, `quat3_to_matrix3`, `quat3_encode/decode_from_uint32` — **but no `quat3_nlerp`/`quat3_slerp`**; the only slerp in the codebase is the allocating object method `Quaternion.slerpQuaternions` (`core/geom/Quaternion.js:1197`). `SmoothingState.js:162-165` even says *"use the static helper variant if available. For now, do a manual lerp+normalize"* — an explicit note that the primitive is missing. Note also `Vector3InterpolationAdapter.js:38-40` uses `core/math/lerp.js` while the other two inline `a + (b - a) * t` 4 and 10 times (mechanical brief F, `inline_lerp`). | `PROMOTION` | Add `core/geom/3d/quaternion/quat3_nlerp.js` — `quat3_nlerp(out, out_offset, ax,ay,az,aw, bx,by,bz,bw, t)`, flat-array, allocation-free, matching the existing `quat3_*` signature convention. All three sites call it. | Low effort / Low risk — pure function, trivially spec'd. |
-| 15 | **MEDIUM** | `TransformInterpolationAdapter` re-derives `TransformReplicationAdapter`'s wire layout by hand; the coupling is documented but unenforced. | `engine/network/adapters/TransformReplicationAdapter.js:45-63` (`serialize`), `:69-86` (`deserialize`); `engine/network/adapters/TransformInterpolationAdapter.js:29-78` (`interpolate`) | `interpolate` reads `Float32 ×3 → readUint32 (packed quat) → v3_binary_equality_decode` twice and writes the same sequence back at `:73-77`. That is a third and fourth hand-written copy of the same field order/precision. Doc at `:15-17` says "matching the wire layout of `TransformReplicationAdapter`". Adding a field to the replication adapter silently makes every interpolated remote Transform garbage — no type, no test, no assert links them. | `UNJUSTIFIED` | Export the layout as three small functions from `TransformReplicationAdapter.js` (`transform_wire_read(buffer, out, offset)`, `transform_wire_write(buffer, px,py,pz, qpacked, sx,sy,sz)`); the replication adapter and the interpolation adapter both call them. Interp keeps only the blend math. | Low effort / Low risk — both have specs (`TransformReplicationAdapter.spec.js`, `TransformInterpolationAdapter.spec.js`). |
-| 16 | **MEDIUM** | `IndexedDBStorage` repeats the transaction+objectStore+request+listener block 4×, and the durability fix was applied to only one copy. | `engine/save/storage/IndexedDBStorage.js:45-76` `remove`, `:78-96` `load`, `:98-147` `store`, `:149-167` `list` | All four: `this.db.then(db => { const transaction = db.transaction(MAIN_STORE_NAME, <mode>); const objectStore = transaction.objectStore(MAIN_STORE_NAME); const idbRequest = objectStore.<op>(…); idbRequest.addEventListener('success'|'error', …) })`. The comment at `:108-112` documents a real correctness lesson — *"A successful request only means the write was queued… Reporting success off the request turns a lost save into a reported save"* — and `store` was fixed to resolve on `transaction.complete` and reject on `transaction.abort`. **`remove` (a write) was not**: `:57-59` still resolves off `idbRequest`'s `success`. Textbook "fix in one place misses the other". | `UNJUSTIFIED` | Private `#with_store(mode, run, resolve, reject)` that opens the transaction, hands the object store to `run`, and wires `complete`/`abort` on the transaction for writes. `remove`/`store` share the write path; `load`/`list` share the read path. | Low effort / Low risk — `IndexedDBStorage.spec.js` exists. Fixing `remove` is a behaviour change (a correct one). |
-| 17 | **MEDIUM** | `FragmentAssembler` and `FragmentRetention` each implement the same bounded Map + FIFO-order-array cache, including a token-identical `#delete`. | `engine/network/transport/fragments/FragmentAssembler.js:95-103` (`#pending` + `#order`), `:150-154` (evict-oldest), `:286-290` (`#delete`), `:280-283` (`clear`); `engine/network/transport/fragments/FragmentRetention.js:72-80`, `:104-107`, `:189-193` (`#delete`), `:183-186` (`clear`) | `#delete(message_id) { this.#map.delete(message_id); const idx = this.#order.indexOf(message_id); if (idx >= 0) this.#order.splice(idx, 1); }` is identical in both. `if (map.size >= cap) { const oldest = order.shift(); if (oldest !== undefined) map.delete(oldest); }` is identical in both. `clear()` is identical. Both are keyed by the same `message_id` space and live side-by-side in `NetworkPeer`'s per-peer connection record (`NetworkPeer.js:674-680`). A third, structurally-similar bounded-key window is `ReliableCommandPipeline.#received_seqs`+`#received_order` (`engine/network/transport/ReliableCommandPipeline.js:150-158`, prune at `:250-256`). | `UNJUSTIFIED` | Promote a `BoundedFifoMap` (or `KeyedFifoCache`) to `core/collection/map/` with `set`, `get`, `delete`, `evict_oldest`, `peek_oldest`, `clear`. All three compose it; per-entry TTL/retry policy stays in the callers. | Low effort / Low risk. |
-| 18 | **MEDIUM / PROMOTION** | Four independent implementations of "per-key monotonic frame watermark map". | `engine/network/state/Baseline.js:16-83` (whole class, `Map<peer,frame>` + monotonic `set_acked`); `engine/network/replication/Replicator.js:104,244,305,322` (`#applied_through` `Map<peer,frame>`); `engine/network/orchestrator/ServerAuthoritativeServer.js:214,238-241,413-418` (`#peer_max_received_frame` `Map<peer,frame>`); `engine/network/orchestrator/ServerAuthoritativeClient.js:52,340-341` (`#last_reconciled_frame`, a `Uint32Map`) | All four store "highest frame seen for key K", all four do the same `const prev = map.get(k); if (prev === undefined || v > prev) map.set(k, v)` guard (or its inline equivalent), and all four need the same "-1 when absent" read and a `forget(key)` on disconnect. `Baseline` is literally that class and already lives in `engine/network/state/`. The backing store choice is also inconsistent (three plain `Map`, one `core/collection/Uint32Map`) with no stated reason. `Replicator.forget_peer` (`:320`) and `Baseline.forget` (`:62`) are the same method written twice. | `UNJUSTIFIED` | Reuse `Baseline` (or rename it `FrameWatermarkMap` and keep `Baseline` as an alias — meep is a library) for all four. Settle on `Uint32Map` for the integer-keyed cases. | Low effort / Low risk — `Baseline` has a spec; the other three have orchestrator-level coverage. |
-| 19 | **LOW** | `Uint8Array`/`TextEncoder` length-prefixed blob framing hand-rolled at 4 sites while a correct primitive exists in one. | primitive: `engine/ecs/storage/binary/object-v2/objectStringCodec.js:29-48`; re-derived: `engine/network/orchestrator/NetworkPeer.js:1150-1156` + `:607-615` (DISCONNECT label, `uint8` length + `TextEncoder`/`TextDecoder`), `engine/network/diagnostics/ReplayLog.js:110-113` + `:129-132` (`uvar` length + bytes), `engine/network/NetworkSession.js:1287-1300` (`ReplaceComponentAction` `uint32` length + bytes) | `writeObjectString`/`readObjectString` is exactly the "byte-length-prefixed, NUL-safe" codec, and its docblock (`objectStringCodec.js:3-8`) explains why `BinaryBuffer.writeUTF8String` cannot be used for arbitrary data. It is buried inside `object-v2` and invisible to `engine/network`, which reinvented it (with a silent 255-byte truncation at `NetworkPeer.js:1151`). Three length-prefix widths in use (`uint8`, `uvar`, `uint32`) with no shared convention. | `PROMOTION` | Move `writeObjectString`/`readObjectString` to `core/binary/` as `binary_write_string_prefixed` / `binary_read_string_prefixed` (+ a `bytes` sibling), re-export from `object-v2` for compatibility. `NetworkPeer.send_disconnect`/dispatch use it. | Low effort / Low risk. |
-| 20 | **LOW** | `SmoothingState` inlines two existing core primitives verbatim. | `engine/network/sim/SmoothingState.js:132-137` (quaternion multiply-by-conjugate); `engine/network/sim/SmoothingState.js:155` (`Math.sqrt(ex*ex + ey*ey + ez*ez)`) | Lines 134-137 are the *identical four expressions* as `core/geom/3d/quaternion/quat3_multiply.js:27-30` (`aw*bx + ax*bw + ay*bz - az*by`, …), just with the second operand pre-conjugated at `:133`. Line 155 re-derives `core/geom/vec3/v3_length.js` (mechanical brief F, `inline_length3`). Both primitives exist, are tested (`quat3_multiply.spec.js`), and this is cold code (once per corrected entity per frame). | `UNJUSTIFIED` | `quat3_multiply(s.orientation_error, 0, px,py,pz,pw, -qx,-qy,-qz,qw)` and `v3_length(ex,ey,ez)`. | Trivial effort / Low risk. |
-| 21 | **LOW** | Two inline fixed-size sample rings with full-window scans, while `core/collection/RingBuffer.js` and `array_compute_min_max` exist. | `engine/network/time/AdaptiveRenderDelay.js:124-128` (`#lateness` Float64Array + `#index` + `#filled`), scan at `:183-189`; `engine/network/time/TimeSync.js:51-64` (`#rtt_samples`/`#offset_samples` + `#sample_cursor`), scan at `:106-116` | Both: fixed `Float64Array`, cursor `(i + 1) % capacity`, then an O(n) pass over the whole window to find an extreme. `AdaptiveRenderDelay`'s min/max pass is `core/collection/array/array_compute_min_max`. `TimeSync`'s is an argmin over one array with a parallel array read — genuinely needs the paired index, so `array_compute_min` doesn't fit. | `AdaptiveRenderDelay`: `UNJUSTIFIED` (use `array_compute_min_max`). `TimeSync`: `JUSTIFIED (paired argmin over two parallel arrays; no core primitive matches)` | Swap the `AdaptiveRenderDelay` scan for `array_compute_min_max`. Leave the ring storage alone — both are perf-shaped fixed typed arrays and `RingBuffer` is an object-slot ring. | Trivial effort / Low risk. |
-| 22 | **LOW** | `#grow_*` typed-array doubling written twice, token-identical. | `engine/network/replication/Replicator.js:404-409` `#grow_record_bounds`; `engine/network/sim/RewindEngine.js:176-181` `#grow_record_starts` | `const old = this.#x; const next = new Int32Array(old.length * 2); next.set(old); this.#x = next;` — identical in both files, and these are the only two `old.length * 2` grow sites in `engine/`+`core/`. | `UNJUSTIFIED` | `core/collection/array/typed/typed_array_grow(array, min_length)` returning the (possibly same) array. Also usable by `ReplicationSlotTable.#grow` (`engine/network/state/ReplicationSlotTable.js:198-210`), which does the same with two arrays and a `fill(-1)`. | Trivial effort / Low risk. |
-| 23 | **LOW** | `seq16_advance` bypassed for an inline `& 0xFFFF`. | `engine/network/orchestrator/NetworkPeer.js:917` (`this.#next_fragment_message_id = (this.#next_fragment_message_id + 1) & 0xFFFF;`) vs `engine/network/core/sequence/seq16.js:67` `seq16_advance` | The `seq16` module is the single home for 16-bit modular sequence arithmetic and is used correctly by `Channel.js:167`. This one site open-codes it. Cosmetic today, but the whole point of the module is that every wrap-safe operation goes through it. | `UNJUSTIFIED` | `seq16_advance(this.#next_fragment_message_id)`. | Trivial effort / Trivial risk. |
-| 24 | **LOW** | `Storage`'s promise wrappers are re-derived by its own consumer instead of being used. | `engine/save/Storage.js:36-40,49-53,76-78,95-97,117-119` (`promiseLoadBinary`, `promiseStoreBinary`, `promiseList`, `promiseRemove`, `promiseContains`); `engine/save/StorageBackedList.js:88-90` and `:132-134` | `StorageBackedSet` writes `new Promise((resolve, reject) => this.storage.store(this.key, list, resolve, reject, noop))` twice, and a 3-level callback pyramid at `:47-68` for read — while `Storage` already exposes `promiseStoreBinary`/`promiseLoadBinary`/`promiseContains`. The two hand-written copies are already inconsistent (`:89` passes `noop` for `progress`, `:133` omits it). `Storage` has `promiseStoreBinary` but no `promiseStore`, which is presumably why the consumer gave up. | `UNJUSTIFIED` | Add `promiseStore`/`promiseLoad` alongside the existing `promiseStoreBinary`/`promiseLoadBinary` in `Storage`, and have `StorageBackedSet` use them. | Trivial effort / Low risk. |
-| 25 | **LOW** | "What is this class's serialized name?" resolved by 5 different rules across the serialization layer. | `engine/ecs/storage/binary/object-v2/BinaryObjectSerializer.js:269-272`; `engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter.js:59-67`; `engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter2.js:324-337`; `engine/ecs/storage/binary/BinarySerializationRegistry.js:57-67`; `engine/ecs/storage/BinaryBufferSerializer.js:140-144` | object-v2 does `registry.getClassName(ctor)` then an **own-property** `typeName` check (guarding against a subclass inheriting its ancestor's `typeName`); v1 does a bare `Object.getPrototypeOf(object).constructor.typeName` (walks the prototype chain — the divergence is already logged in `src/REVIEW_2026_08_06/engine-ecs.md:665-669`); Adapter2 does `class_registry.findNamesByModule(ctor)` with a `ctor.typeName` fallback; the registry and `BinaryBufferSerializer` each do their own bare `typeName` read with different error text. | `UNJUSTIFIED` | One `binary_resolve_type_name(registry, ctor)` in `engine/ecs/storage/binary/` implementing object-v2's (correct) rule. All five sites call it. | Low effort / Low risk. |
-
-## Serialization surface census
-
-"Would a field change need editing here?" = if you add/remove/reorder a field on the type, must this site be edited by hand?
-
-### `Transform` (`engine/ecs/transform/Transform.js`)
-
-| # | Encoding | Path | Layout | Field change needs edit? |
-|---|---|---|---|---|
-| 1 | JSON | `engine/ecs/transform/Transform.js:252` `toJSON` / `:226` `fromJSON` | `{position, rotation, scale}` delegating to the value types' own `toJSON` | **Yes** |
-| 2 | Save-game binary | `engine/ecs/transform/TransformSerializationAdapter.js:18` / `:45` | 3×Float64 pos, uint32 packed quat, equality-encoded scale | **Yes** |
-| 3 | Network wire binary | `engine/network/adapters/TransformReplicationAdapter.js:45` / `:69` | 3×Float32 pos, uint32 packed quat, equality-encoded scale | **Yes** |
-| 4 | Network wire binary (read+write, *third* copy of layout #3) | `engine/network/adapters/TransformInterpolationAdapter.js:29` `interpolate` | reads #3 twice, writes #3 once | **Yes** — and silently, with no error |
-| 5 | Local interpolation binary | `engine/interpolation/TransformPoseSerializationAdapter.js:30` / `:46` | 7×Float64 (pos + quat, no scale) | **Yes** |
-| 6 | object-v2 reflection | `engine/ecs/storage/binary/object-v2/BinaryObjectSerializer.js:309` `#writeReflected` via `Object.keys` | own enumerable fields incl. `matrix`, `flags` | No (reflective) — but produces a *different* field set than 1–5 |
-
-**5 hand-written encodings of one type.** #2/#3/#4 share a field order that nothing enforces.
-
-### `Vector3` (`core/geom/Vector3.js`)
-
-| # | Encoding | Path | Field change needs edit? |
-|---|---|---|---|
-| 1 | JSON | `core/geom/Vector3.js:1014` / `:1026` | Yes |
-| 2 | Float64 binary (`@deprecated`) | `core/geom/Vector3.js:1044` / `:1055` | Yes |
-| 3 | Float32 binary (`@deprecated`) | `core/geom/Vector3.js:1068` / `:1079` | Yes |
-| 4 | Equality-compressed binary | `core/geom/vec3/serialization/v3_binary_equality_encode.js` / `_decode.js` | Yes |
-| 5 | Float32 interpolation | `engine/network/adapters/Vector3InterpolationAdapter.js:27` | Yes |
-| 6–14 | 9 inline open-codings inside component adapters | `TransformSerializationAdapter.js:24`, `TransformPoseSerializationAdapter.js:33`, `TransformReplicationAdapter.js:51`, `RigidBodySerializationAdapter.js:33,37,43`, `JointSerializationAdapter.js:30-31`, `TopDownCameraControllerSerializationAdapter.js:16`, `GamepadStickCalibration.js:101`, `PathSerializationAdapter.js:30`, `TerrainSerializationAdapter.js:37,40,90` | Yes, each |
-
-**~14 independent encodings.** Only #4 is a shared primitive with a spec.
-
-### `Quaternion` (`core/geom/Quaternion.js`)
-
-| # | Encoding | Path | Field change needs edit? |
-|---|---|---|---|
-| 1 | JSON | `core/geom/Quaternion.js:1345` / `:1359` | Yes |
-| 2 | Float64 binary | `core/geom/Quaternion.js:1367` / `:1378` | Yes |
-| 3 | Float32 binary | `core/geom/Quaternion.js:1391` / `:1402` | Yes |
-| 4 | Smallest-three uint32 | `core/geom/3d/quaternion/quat3_encode_to_uint32.js` / `quat3_decode_from_uint32.js` (alias files `quat_*` re-export) | Yes |
-| 5 | Float32 interpolation | `engine/network/adapters/QuaternionInterpolationAdapter.js:14` | Yes |
-| 6 | Inline in Transform pose adapter | `engine/interpolation/TransformPoseSerializationAdapter.js:36-39,51-53` | Yes |
-
-### `Vector4` / `Vector2` / `Vector1` / `Color`
-
-| Type | Encodings | Paths |
-|---|---|---|
-| `Vector4` | JSON + Float64 binary | `core/geom/Vector4.js:437`/`:446`, `:454`/`:465` |
-| `Vector2` | JSON + Float64 binary + Float32 binary | `core/geom/Vector2.js:422`/`:426`, `:439`/`:448`, `:459`/`:468` |
-| `Vector1` | JSON + Float64 binary | `core/geom/Vector1.js:270`/`:278` |
-| `Color` | JSON + Float32 binary (`@deprecated`) + CSS-string `parse` | `core/color/Color.js:571`/`:567`, `:642`/`:653`, `:664` |
-
-`Vector4.fromBinaryBuffer` (`:465`) and `Quaternion.fromBinaryBuffer` (`:1378`) are **literally identical** (4× `readFloat64` + `set`); `Color.fromBinaryBuffer` (`:653`) is the same shape at Float32. See dismissed leads — this one is justified.
-
-### `NetworkIdentity` (the only ECS component with a *single* encoding)
-
-| # | Encoding | Path |
-|---|---|---|
-| 1 | Save-game binary | `engine/network/ecs/serialization/NetworkIdentitySerializationAdapter.js:36` / `:59` |
-
-Deliberately never on the wire (`:19-22`) — the counter-example that shows one encoding is achievable when the design says so.
-
-### Summary
-
-`Transform` has **5** hand-maintained binary/JSON encodings, `Vector3` ~**14**, `Quaternion` **6**. A field-layout change to `Transform` requires 5 coordinated edits, **none of which is enforced by a type, an assert, or a shared test**; the `TransformReplicationAdapter` ⟷ `TransformInterpolationAdapter` pair (#3/#4) is coupled by a prose comment only, and a mismatch there corrupts every interpolated remote entity with no error.
-
-## Dismissed leads
-
-- **`Color.fromBinaryBuffer` / `Quaternion.fromBinaryBuffer` / `Vector4.fromBinaryBuffer` token-identical (mechanical brief A).** JUSTIFIED: 5-line leaf codecs; a `read_float_tuple(buffer, n, precision)` primitive would need a precision selector (Color is f32, the others f64) — a sentinel parameter the house rules reject — and adds a call layer to the lowest-level codec for no maintenance win. The *real* problem is finding #3 (no shared vector codec used by adapters), not these methods.
-- **`seq16.js` vs `seq32.js` (near-identical API and `greater_than` body).** JUSTIFIED: `seq32_greater_than`/`seq32_distance` must use Number arithmetic because JS bitwise operators sign-extend at bit 31 (documented at `seq32.js:36-38`); a shared implementation would be wrong for one of them. Separately noted: `seq32_*` has **no production callers** (only its own spec) — library surface, not dead code, so leave it.
-- **Hand-written per-class `BinaryClassSerializationAdapter` subclasses looking alike.** JUSTIFIED by explicit design bet (action-log replication with hand-written adapters). The duplication that *is* worth fixing is the missing value-type codec primitives underneath them (#3), not the adapters.
-- **`BinaryObjectSerializer.writeValue` vs `BinaryObjectDeSerializer.readValue`, `serialize` vs `deserialize`, `snapshotter_emit` vs `snapshotter_apply`.** JUSTIFIED: encode/decode pairs are inherently mirrored; the format constants are already shared via `ObjectBinaryFormat.js` (which is why the mechanical brief flagged the import block, not the logic).
-- **`BinaryCollectionSerializer.setRegistry`/`setBuffer` vs `BinaryCollectionDeSerializer.setRegistry`/`setBuffer`; `BinaryObjectSerializer.setRegistry` vs `BinaryObjectDeSerializer.setRegistry`.** 4-line assertion setters. Too small; a shared base class would be ceremony.
-- **`SimActionRegistry` vs `ReplicatedComponentRegistry` "assign a sequential uint8 type_id, cap at 256".** ~6 shared lines inside otherwise-unrelated classes (one owns an object pool, the other an adapter cache). Not worth a shared base.
-- **`SimActionRegistry`'s per-type object pool vs `core/model/object/ObjectPoolFactory`.** Checked: the registry pool is a `SimAction[][]` indexed by `type_id` with `reset()`-on-acquire; `ObjectPoolFactory` is per-class with a factory callback. Swapping would need one factory per action class registered at `register()` time. Marginal.
-- **`ReplicationSlotTable`'s free-list + highwater vs `core/IdPool`.** Checked `core/IdPool.js`: it is `BitSet`-backed with `nextClearBit` allocation (lowest-free-first). `ReplicationSlotTable` needs LIFO recycling *plus* a per-slot generation counter *plus* the reverse `entity→network` map, and deliberately keeps ids dense in a typed array. Different enough.
-- **`JitterBuffer.push` sorted-insert vs `ServerAuthoritativeServer.#track_referenced_frame` sorted-insert.** Both already use `core/collection/array/binarySearchHighIndex` — this is reuse working correctly, not duplication.
-- **`SimulatedTransport`'s linear insertion-sort into `in_queue` (`:163-166`) vs `JitterBuffer`.** SimulatedTransport is a test/prototype link simulator; the insert is O(n) by design for tiny queues. Cold code, different key.
-- **`SyncTest.__fnv_byte` (`engine/network/diagnostics/SyncTest.js:58`) vs `core/collection/array/typed/uint8_array_hash`.** Checked both: the core hash is a DJB-style word-at-a-time hash with no incremental accumulator, while `fingerprint_world` must interleave entity_id and type_id bytes between component payloads. Not a drop-in. Noted, not filed.
-- **`ScopeFilter` / `owner_authorization` / `ChangedEntitySet` / `PriorityAccumulator` / `MutationLedger` / `TimeDilation`.** Read; no duplication found.
-
-## Notes — why duplication accumulates here
-
-1. **Wire formats are documented, not typed.** `ActionLog.js:10-22`, `Replicator.js:26-35`, `Snapshotter.js:19-29`, `Channel.js:9-16`, `fragment_send.js:12-21`, `TransformReplicationAdapter.js:23-28` all describe their byte layout in a docblock and then hand-write the reader and writer separately. Nothing in the language couples them, so every new consumer of a format writes a fresh parser (finding #1: five parsers for one format). The one place this was done right — `ObjectBinaryFormat.js` as a shared constants module — is exactly the place the mechanical pass found *no* logic duplication.
-
-2. **Three generations of object serializer were built without retiring the previous one.** v1 (`object/BinaryObjectSerializationAdapter`) is wired; v2 (`object/BinaryObjectSerializationAdapter2`) has zero importers; v3 (`object-v2/`) has a README, a DESIGN.md, four spec files, and zero production consumers. Each generation re-derived the primitive-tag switch and the interning table from scratch rather than extending its predecessor. "meep is a library, unreferenced exports are public surface" protects v3 (documented, spec'd, intended to be used) but not v2 (undocumented intermediate with no spec).
-
-3. **`Transport.js` was written as a base class but only used as an interface.** It has default `getStats`, `connect`, `disconnect` implementations (`:95-111`), and six subclasses that override all three with copies of each other rather than calling up. The `#disconnect_fired` latch was invented three times independently — and forgotten on the fourth adapter (`WebTransportTransport`), which is now behaviourally inconsistent.
-
-4. **`core/` primitives are hard to discover from `engine/network/`.** `quat3_multiply` is inlined verbatim in `SmoothingState.js` with a comment saying the helper doesn't exist; `lerp` is used in one interpolation adapter and inlined 14× in the other two; `v3_length` is inlined; `objectStringCodec`'s length-prefixed codec is reinvented in `NetworkPeer`. There is a real gap too — no `quat3_nlerp` exists anywhere — but three of the four cases are pure discovery failure.
-
-5. **Parallel-array containers invite copy-paste compaction.** `ServerAuthoritativeServer`'s four `#pending_*` arrays forced two 19-line compaction methods (#10) and two dedup triple-comparison loops (`:454-459` and `:567-572`). `core/collection/table/RowFirstTable` exists for exactly this and is not used here — worth considering if a fifth column is ever added.
-
-6. **One real correctness consequence, already latent.** Finding #16 (`IndexedDBStorage.remove` never got the transaction-durability fix that `store` did) and finding #4 (AUTH_STATE writer/reader skip on different predicates) are both live divergences produced by this pattern, not hypotheticals.
-
-7. **Out of scope but noted (house rule: don't silently catch).** `engine/network/orchestrator/ServerAuthoritativeClient.js:379-386` wraps `rewind_engine.rewind_to` in a `try { … } catch (e) { return; }` that swallows every error, not just the anticipated "log rolled past server_frame". `engine/save/storage/IndexedDBStorage.js:120-125` (`get_bound_address`-style `catch → return null`) and `WebTransportTransport.js:148-155` (three `catch (_) { /* swallow */ }`) are the same shape. Separate concern from duplication.
+# Domain G — engine/network + engine/save + engine/ecs/storage
+
+Source root for all paths: `H:/git/moh/app/src/mir-engine/meep/src/`.
+Every finding below was verified by opening the cited files. `*.spec.js` and `prototype*/test*` harnesses excluded.
+
+## Findings
+
+| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
+|---|---|---|---|---|---|---|---|
+| 1 | **CRITICAL** | **The ActionLog record wire-format is hand-parsed in 5 independent places** (written in 1). Format is documented only in a comment block, never in code. | writer: `engine/network/sim/SimActionExecutor.js:242-302` `execute`; readers: `engine/network/replication/Replicator.js:335` `#scan_record_in_scope`, `engine/network/replication/Replicator.js:376` `#copy_action_to`, `engine/network/sim/RewindEngine.js:119` `#skip_record`, `engine/network/sim/RewindEngine.js:143` `#restore_prior_state`, `engine/network/orchestrator/ServerAuthoritativeServer.js:502` `#read_historical` | All five readers repeat the identical 8-line prologue: `readUintVar()` prior_count → loop{`readUintVar` entity_id, `readUint8` component_type_id, `readUint32` payload_len, `position += len`} → `readUint8` action_type_id → `readUint8` sender_id → `readUint32` action_payload_len. `Replicator.js:359` and `RewindEngine.js:130` both carry the same `// sender_id` comment. Format spec lives in `engine/network/sim/ActionLog.js:10-22` (a docblock). Changing the payload_len width, adding a field, or reordering requires 6 coordinated edits with zero compile-time coupling; one miss silently misparses every subsequent record in the frame. | `UNJUSTIFIED` | One `engine/network/sim/action_record.js` module: `action_record_write_prior(buffer, ...)`, `action_record_read_header(buffer, out)`, `action_record_skip(buffer)`. Readers 3–5 become 1-line calls; `#restore_prior_state`/`#read_historical` keep only their per-entry payload handling. | Medium effort / Medium risk — hot path, but `sim_action.spec.js`, `RewindEngine.spec.js`, `Replicator.spec.js`, `ServerAuthoritative.spec.js` cover it end-to-end. |
+| 2 | **HIGH** | **`ActionLog` and `InputRing` are the same per-frame ring of `BinaryBuffer` slots**, written twice. | `engine/network/sim/ActionLog.js:39-189` (class `ActionLog`); `engine/network/state/InputRing.js:28-173` (class `InputRing`) | Both hold `#buffers: BinaryBuffer[]`, `#frame_numbers: Int32Array` filled `-1`, `#write_ends: Int32Array`, index by `frame % frame_capacity`. `ActionLog.js:49-95` vs `InputRing.js:37-73` constructors are 97% token-identical (mechanical brief C, sim=0.969) — same validation throw, same three allocations, same `setCapacity` loop. `buffer_for` (`ActionLog.js:165` / `InputRing.js:124`) and `write_end_for` (`ActionLog.js:181` / `InputRing.js:139`) are token-identical. Only the *framing policy* differs: ActionLog has explicit `begin_frame`/`end_frame` (open-frame state), InputRing has a single atomic `write(frame, writer)`. The `has()` vs `has_frame()` naming divergence is pure accident. | `UNJUSTIFIED` | Promote a `FrameBufferRing` to `core/collection/` (or `engine/network/state/`) owning `frame_capacity`, `#buffers`, `#frame_numbers`, `#write_ends`, `has(frame)`, `buffer_for(frame)`, `write_end_for(frame)`, `slot_begin(frame)`, `slot_commit(frame)`. `ActionLog` composes it and adds the open-frame guard; `InputRing` composes it and adds `write`/`for_each_in_range`. Do **not** unify via a sentinel/flag parameter (house rule). | Low effort / Low risk — both classes have direct specs; the extracted primitive is ~70 lines with no behaviour change. |
+| 3 | **HIGH** | **No shared binary codec exists for the engine's own value types; every adapter open-codes `write 3 floats`.** Systemic, not per-file. | `engine/ecs/transform/TransformSerializationAdapter.js:24-26`; `engine/interpolation/TransformPoseSerializationAdapter.js:33-39`; `engine/network/adapters/TransformReplicationAdapter.js:51-53`; `engine/network/adapters/Vector3InterpolationAdapter.js:29-31,42-44`; `engine/physics/ecs/RigidBodySerializationAdapter.js:33,37,43`; `engine/physics/ecs/JointSerializationAdapter.js:30-31`; `engine/graphics/ecs/camera/topdown/TopDownCameraControllerSerializationAdapter.js:16`; `engine/input/devices/gamepad/GamepadStickCalibration.js:101`; `engine/navigation/ecs/components/PathSerializationAdapter.js:30` | Nine files each write `buffer.writeFloatNN(v.x); …(v.y); …(v.z);` inline. `Vector3.toBinaryBuffer` (`core/geom/Vector3.js:1044`) and `toBinaryBufferFloat32` (`:1068`) exist and are marked `@deprecated` — deprecated in favour of *nothing*, so callers regressed to inline code. Meanwhile `core/geom/vec3/serialization/v3_binary_equality_encode.js`/`_decode.js` **is** the shape that works and is reused by exactly 3 adapters (`TransformSerializationAdapter.js:37,52`, `TransformReplicationAdapter.js:62,79`, `TransformInterpolationAdapter.js:37,46,77`) — proof the primitive pattern is viable and already half-built. | `PROMOTION` | Add `core/geom/vec3/serialization/v3_binary_write_f32/_f64` + `v3_binary_read_f32/_f64(buffer, out, offset)`, and `v4_`/`quat3_` siblings next to the existing `v3_binary_equality_*`. Delete the `@deprecated` `Vector*.toBinaryBuffer*` methods' bodies in favour of delegating (they are public library surface — keep the names). | Low effort / Low risk per site; the value is that a precision or endianness change becomes one edit. |
+| 4 | **HIGH** | **AUTH_STATE payload is an untagged concatenation whose writer and reader are two independently-written loops.** A skip on one side silently desynchronizes the whole payload. | writer: `engine/network/NetworkSession.js:1481-1506` `#send_auth_state_for_entity`; reader: `engine/network/NetworkSession.js:1912-1920` `onApplyAuthState` handler | Writer iterates `this.#replicated`, `continue`s when `world.getComponent(entity_id, ComponentClass) === undefined`, and calls `adapter.serialize(buf, live)` — **no per-component tag, no length prefix**. Reader iterates the same map and `continue`s when the *receiver's* `getComponent` is undefined. The two skip predicates evaluate on different worlds. If host and client component composition differ for one entity (common during spawn/despawn races), the reader deserializes component N's bytes into component N+1. The comment at `:1910` ("Mirrors the host's serialize order") is the only thing enforcing the invariant. | `UNJUSTIFIED` | Both loops call one `#for_each_replicated(entity_id, cb)` helper, and the payload gains a `uint8 type_id + uint32 len` frame per component — the same framing `Snapshotter` already uses (`engine/network/sim/Snapshotter.js:82-91`). That makes reader skips independent of writer skips. | Medium effort / Medium risk — wire-format change; `ServerAuthoritative.spec.js` and `NetworkPeer.auth_state.spec.js` are the gate. |
+| 5 | **HIGH** | **Three complete tagged-value object-graph serializers coexist**, two of them with no production consumer. | `engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter.js` (v1, 130 lines); `engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter2.js` (v2, 493 lines); `engine/ecs/storage/binary/object-v2/BinaryObjectSerializer.js` + `BinaryObjectDeSerializer.js` (v3, 331+315 lines) | `BinaryObjectSerializationAdapter2.js:3-14` declares `HEADER_TAG_NULL/UNDEFINED/BOOLEAN_TRUE/BOOLEAN_FALSE/POSITIVE_INTEGER/NEGATIVE_INTEGER/FLOAT/STRING`; `object-v2/ObjectBinaryFormat.js:31-45` declares `TAG_NULL/UNDEFINED/FALSE/TRUE/POS_INT/NEG_INT/FLOAT/STRING` — same eight concepts, different numbering. `Adapter2.#trySerializePrimitive` (`:263-310`) and `BinaryObjectSerializer.writeValue` (`:195-238`) are the same `switch (typeof value)` with the same int/varint-vs-float64 split; `Adapter2.deserialize` (`:442-486`) and `BinaryObjectDeSerializer.readValue` (`:182-227`) the same tag switch. Adapter2 additionally reimplements the shape/schema table (`#writeSchema`/`#readSchema` `:194-255`, class `SchemaTable` `:92-151`) that object-v2 implements as `#internShape`/shape table. **Grep shows `BinaryObjectSerializationAdapter2` has zero importers anywhere in `src/`**, and object-v2 has none outside its own README/DESIGN/specs/`serializerTestHarness.js`. Only v1 is wired (`engine/ecs/storage/BinaryBufferSerializer.js:125`, `BinaryBufferDeSerializer.js:108`, `engine/intelligence/blackboard/BlackboardDynamicStorageAdapter.js:44`, `engine/sound/sopra/serialization/*`). | `UNJUSTIFIED` | object-v2 is strictly the superset (refs/cycles, class table, shape table, bidirectional migration). Delete `BinaryObjectSerializationAdapter2.js` — it is an abandoned intermediate, not library surface anyone can be using (no importers, no spec). Then migrate `BinaryBufferSerializer/DeSerializer` to object-v2 and reduce v1 to a shim, or explicitly document v1 as the ECS-collection path and object-v2 as the graph path. | Deleting Adapter2: trivial. Migrating v1→v3: high effort / high risk (save-file format), and should be a separate decision. |
+| 6 | **HIGH** | **"Resolve the migrator chain for a stored version, or throw" is written 3×, and the three have divergent up/down policies.** | `engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter.js:104-118` `deserialize`; `engine/ecs/storage/binary/collection/BinaryCollectionDeSerializer.js:215-232` `initialize`; `engine/ecs/storage/binary/object-v2/BinaryObjectDeSerializer.js:278-302` `#readAdapterObject` | All three: read stored `version` → compare to `adapter.version` → `registry.getUpgradersChain(name, version, adapter.version)` → throw if `null` → `executeBinaryClassUpgraderChain(chain, buffer, tmp0, tmp1)`. But `BinaryCollectionDeSerializer.js:215` **throws outright** when `version > adapter.version`, whereas `BinaryObjectDeSerializer.js:279` explicitly supports it ("migrate up OR down to the adapter's current version") and v1 (`:108`) just tests `!==`. Same registry, same upgrader graph, three different downgrade policies. Buffer management also diverges: v1 reuses two long-lived `__upgradeBuffer0/1` fields (`:24-30`), object-v2 allocates a fresh pair per object (`:301`), collection resets its pair per `initialize` (`:235-236`). | `UNJUSTIFIED` | One `binary_migrate_payload(registry, typeName, stored_version, adapter, buffer)` in `engine/ecs/storage/binary/`, returning the migrated buffer or the original. Pick one downgrade policy and document it. | Low effort / Medium risk — the behaviour unification is the risky part, not the extraction. |
+| 7 | **MEDIUM** | `NetworkSession.normalize_if_dirty` and `#render_interpolated_entities` share a verbatim 18-line nested traversal. | `engine/network/NetworkSession.js:1063-1082` (inside `normalize_if_dirty`); `engine/network/NetworkSession.js:2003-2023` (inside `#render_interpolated_entities`) | Identical body: `for (const entity_id of this.#remote_entities)` → `getComponent(entity_id, NetworkIdentity)` guard → `for (const [ComponentClass, desc] of this.#replicated)` → `desc.interp === null` guard → live-component guard → `scratch.position = 0` → `#interp_log.interpolate(scratch, identity.network_id, desc.interp_type_id, …)` → `if (!ok) continue` → `scratch.position = 0` → `binary_registry.getAdapter(ComponentClass.typeName).deserialize(scratch, live)`. The only differences are the `(tick, tick, 0)` vs `(tick_a, tick_b, t)` arguments and a `wrote_anything = true` line. The same outer traversal appears a third time (serializing, not deserializing) at `:1947-1959` `#on_frame_applied`. | `UNJUSTIFIED` | Extract `#apply_interpolated(tick_a, tick_b, t) → boolean`. `normalize_if_dirty` calls it with `(tick, tick, 0)`; `#render_interpolated_entities` calls it with the computed triple and uses the return for `render_dirty`. Extract `#for_each_remote_replicated(cb)` for the shared outer walk so `#on_frame_applied` uses it too. | Low effort / Low risk. |
+| 8 | **MEDIUM** | Transport adapters copy-paste their entire stats and disconnect-latch machinery instead of putting it on the `Transport` base. | `getStats()` ×6: `engine/network/transport/LoopbackTransport.js:186`, `engine/network/transport/adapters/SimulatedTransport.js:244`, `.../WebRTCDataChannelTransport.js:123`, `.../WebSocketTransport.js:172`, `.../NodeUDPTransport.js:198`, `.../WebTransportTransport.js:161`. Latch: `WebSocketTransport.js:61,89-90,159`, `WebRTCDataChannelTransport.js:49,63-64,70-71,109`, `NodeUDPTransport.js:59,81-82,88-89,168,184`. Base class: `engine/network/transport/Transport.js:29-112` | All six `getStats()` bodies are the identical 6-line field-by-field copy of a `{bytes_in, bytes_out, packets_in, packets_out}` object; all six declare `#stats = { bytes_in: 0, … }`. Three adapters independently implement the "`#disconnect_fired` latch so a local `disconnect()` doesn't echo `onDisconnect`" idiom, each with its own copy of `if (this.#disconnect_fired) return; this.#disconnect_fired = true; this.onDisconnect.send1(reason);`. **`WebTransportTransport` has no latch at all** (`:146-156` `disconnect()`), so it *does* echo — the divergence a shared base would have prevented. `disconnect()` is token-identical (65 tokens) between `SimulatedTransport.js:228` and `LoopbackTransport.js:166` (mechanical brief A). `send()` is token-identical (64 tokens) between `WebRTCDataChannelTransport.js:87` and `WebSocketTransport.js:103`; `NodeUDPTransport.js:131` is the same plus a remote-null check — all three compute `const payload = (length === bytes.byteLength) ? bytes : bytes.subarray(0, length)`. | `UNJUSTIFIED` | Move `#stats` + `getStats()` + protected `count_in(n)`/`count_out(n)` onto `Transport`. Add a protected `fire_disconnect_once(reason)` + `latch_disconnect()` pair there. Add a `transport_trim_payload(bytes, length)` helper (or accept the 1-liner). Leave the paired `disconnect()` of Loopback/Simulated as-is unless the pair-unbinding is hoisted to a shared `PairedTransport` base. | Low effort / Low risk — `Transport.js` already exists precisely as the shared base and is under-used. |
+| 9 | **MEDIUM** | `send_fragmented` and `resend_fragment_chunk` duplicate the fragment header write, the chunk-slice math, and — with two *different formulas* — the `total_chunks` derivation. | `engine/network/transport/fragments/fragment_send.js:69-86` (`send_fragmented` loop body); `engine/network/transport/fragments/fragment_send.js:127-146` (`resend_fragment_chunk`) | Both compute `chunk_offset = i * MAX_FRAGMENT_CHUNK_BYTES`, `remaining`, `chunk_size = remaining < MAX ? remaining : MAX`, then write the identical 5-byte header (`scratch[0]=type; scratch[1]=id&0xFF; scratch[2]=(id>>8)&0xFF; scratch[3]=index; scratch[4]=total`), `scratch.set(payload.subarray(...), FRAGMENT_HEADER_BYTES)`, `send_fn(scratch, FRAGMENT_HEADER_BYTES + chunk_size)`. `total_chunks` is `Math.ceil(len/MAX)` at `:61` but `len <= MAX ? 1 : Math.ceil(len/MAX)` at `:127-129`. The doc at `:96-97` states the invariant ("The wire layout matches what `send_fragmented` would have produced") in prose because nothing enforces it — and a retransmitted chunk that carries a different `total_chunks` than the original makes the receiver drop the whole assembly (`FragmentAssembler.js:168-173`). | `UNJUSTIFIED` | One module-private `write_fragment_chunk(payload, payload_length, message_id, chunk_index, total_chunks, type, scratch, send_fn)` and one `fragment_total_chunks(payload_length)`. Both exports become thin loops/guards over it. | Low effort / Low risk — `fragment_send` has a spec and the NACK path has `NetworkPeer` integration coverage. |
+| 10 | **MEDIUM** | `ServerAuthoritativeServer` compacts its 4 parallel pending arrays with two near-verbatim 19-line methods differing only in an inequality. | `engine/network/orchestrator/ServerAuthoritativeServer.js:597-616` `#pending_trim_to_window`; `engine/network/orchestrator/ServerAuthoritativeServer.js:634-653` `#pending_filter_to_future` | Byte-for-byte identical apart from `>= window_oldest` vs `> keep_threshold`: same `kept` cursor, same four `[kept] = [i]` assignments, same four `.length = kept` truncations, same `#pending_referenced_frames.length = 0` + rebuild loop. The code says so itself at `:629-631`: *"Same structural pattern as `__pending_trim_to_window` but with the inequality flipped"*. Adding a fifth parallel array means editing both. | `UNJUSTIFIED` | Single `#pending_keep_from(min_frame)` — callers pass `window_oldest` and `keep_threshold + 1`. Uniform control flow, no predicate parameter, no sentinel. | Trivial effort / Low risk — `ServerAuthoritative.spec.js` covers both paths. |
+| 11 | **MEDIUM** | `snapshotter_apply` and `snapshotter_apply_to_existing` are two hand-written parsers of one wire format, with divergent bounds handling. | `engine/network/sim/Snapshotter.js:108-151` `snapshotter_apply`; `engine/network/sim/Snapshotter.js:176-222` `snapshotter_apply_to_existing` | Same outer/inner loop, same three `MalformedPacketError` bounds checks (entity overrun, payload overrun, read-past-end) with only the function name changed in the message, same `type_id/payload_len` read, same skip-to-stay-aligned pattern. They differ only in what happens per component: create-entity-and-attach vs look-up-and-deserialize-in-place (three skip cases at `:200-213` vs one at `:134-138`). A future hardening of the length validation must be applied twice. | `UNJUSTIFIED` | One `snapshotter_walk(buffer, buffer_end, on_entity, on_component)` doing the framing + all bounds checks; the two public functions supply the two apply policies. | Low effort / Low risk — `Snapshotter.spec.js` has dedicated malformed-packet tests (`:338`, `:369`). |
+| 12 | **MEDIUM** | `NetworkPeer` repeats the same 6-line send prologue/epilogue across 9 packet-send methods. | `engine/network/orchestrator/NetworkPeer.js` — `send_recovery_request:947`, `send_state_burst_for_range:975`, `send_auth_state:1038`, `send_initial_sync:1064`, `send_resume_hello:1089`, `send_resume_accept:1110`, `send_resume_reject:1125`, `send_disconnect:1144`, `send_time_dilation_feedback:1168` | Each is: `const conn = this.#peers.get(peer_id); if (conn === undefined) throw new Error(\`NetworkPeer.<name>: peer ${peer_id} not connected\`); this.#send_buffer.position = 0; this.#send_buffer.writeUint8(NetworkPacketType.<X>);` … `this.#send_to_peer(conn, this.#send_buffer.raw_bytes, this.#send_buffer.position);` — 9 copies of the connection lookup + error string + buffer reset + type byte + dispatch. This is duplicated *logic* (lookup/throw/reset), not adapter shape. | `UNJUSTIFIED` | Private `#begin_packet(peer_id, method_name, packet_type) → conn` and `#end_packet(conn)`. Each `send_*` keeps only its own field writes. Stays fully typed — no string-keyed dispatch table. | Trivial effort / Low risk. |
+| 13 | **MEDIUM** | The security-critical bounds-checked action-header read is written 3× inside a single method. | `engine/network/replication/Replicator.js:224-231` (deferral path), `:256-263` (skip path), `:272-279` (apply path) | Each block is `if (in_buffer.position + ACTION_HEADER_BYTES > in_buffer_end) throw new MalformedPacketError(...); readUint8(); const len = readUint32(); if (in_buffer.position + len > in_buffer_end) throw new MalformedPacketError(...)`. Three copies of the invariant that gates untrusted-length parsing (comment at `:219-223` explains why it must not be an `assert`). The three error messages have already drifted ("action header overruns packet" vs "…(skip; frame …)" vs "skipped action payload of …"). One missed copy = OOB read / cross-packet leak. | `UNJUSTIFIED` | `#read_action_header(buffer, end, frame, i, count) → payload_len` (or a small `{type_id, payload_len}` out-param object hoisted to a field to avoid allocation). All three call it. | Trivial effort / Low risk — `Replicator.spec.js:644,666` already test malformed lengths. |
+| 14 | **MEDIUM / PROMOTION** | Shortest-path quaternion nlerp (dot-sign-flip → componentwise lerp → normalize) written 3× with no core primitive. | `engine/network/adapters/QuaternionInterpolationAdapter.js:27-42`; `engine/network/adapters/TransformInterpolationAdapter.js:56-65`; a third variant (lerp toward identity) at `engine/network/sim/SmoothingState.js:166-183` | The first two are the same 12 lines: `if (a·b < 0) negate b`, four `q = a + (b - a) * t`, `len2`, `inv_len = len2 > 0 ? 1/Math.sqrt(len2) : 1`, scale. `core/geom/3d/quaternion/` has `quat3_multiply`, `quat3_integrate`, `quat3_from_axis_angle`, `quat3_to_matrix3`, `quat3_encode/decode_from_uint32` — **but no `quat3_nlerp`/`quat3_slerp`**; the only slerp in the codebase is the allocating object method `Quaternion.slerpQuaternions` (`core/geom/Quaternion.js:1197`). `SmoothingState.js:162-165` even says *"use the static helper variant if available. For now, do a manual lerp+normalize"* — an explicit note that the primitive is missing. Note also `Vector3InterpolationAdapter.js:38-40` uses `core/math/lerp.js` while the other two inline `a + (b - a) * t` 4 and 10 times (mechanical brief F, `inline_lerp`). | `PROMOTION` | Add `core/geom/3d/quaternion/quat3_nlerp.js` — `quat3_nlerp(out, out_offset, ax,ay,az,aw, bx,by,bz,bw, t)`, flat-array, allocation-free, matching the existing `quat3_*` signature convention. All three sites call it. | Low effort / Low risk — pure function, trivially spec'd. |
+| 15 | **MEDIUM** | `TransformInterpolationAdapter` re-derives `TransformReplicationAdapter`'s wire layout by hand; the coupling is documented but unenforced. | `engine/network/adapters/TransformReplicationAdapter.js:45-63` (`serialize`), `:69-86` (`deserialize`); `engine/network/adapters/TransformInterpolationAdapter.js:29-78` (`interpolate`) | `interpolate` reads `Float32 ×3 → readUint32 (packed quat) → v3_binary_equality_decode` twice and writes the same sequence back at `:73-77`. That is a third and fourth hand-written copy of the same field order/precision. Doc at `:15-17` says "matching the wire layout of `TransformReplicationAdapter`". Adding a field to the replication adapter silently makes every interpolated remote Transform garbage — no type, no test, no assert links them. | `UNJUSTIFIED` | Export the layout as three small functions from `TransformReplicationAdapter.js` (`transform_wire_read(buffer, out, offset)`, `transform_wire_write(buffer, px,py,pz, qpacked, sx,sy,sz)`); the replication adapter and the interpolation adapter both call them. Interp keeps only the blend math. | Low effort / Low risk — both have specs (`TransformReplicationAdapter.spec.js`, `TransformInterpolationAdapter.spec.js`). |
+| 16 | **MEDIUM** | `IndexedDBStorage` repeats the transaction+objectStore+request+listener block 4×, and the durability fix was applied to only one copy. | `engine/save/storage/IndexedDBStorage.js:45-76` `remove`, `:78-96` `load`, `:98-147` `store`, `:149-167` `list` | All four: `this.db.then(db => { const transaction = db.transaction(MAIN_STORE_NAME, <mode>); const objectStore = transaction.objectStore(MAIN_STORE_NAME); const idbRequest = objectStore.<op>(…); idbRequest.addEventListener('success'|'error', …) })`. The comment at `:108-112` documents a real correctness lesson — *"A successful request only means the write was queued… Reporting success off the request turns a lost save into a reported save"* — and `store` was fixed to resolve on `transaction.complete` and reject on `transaction.abort`. **`remove` (a write) was not**: `:57-59` still resolves off `idbRequest`'s `success`. Textbook "fix in one place misses the other". | `UNJUSTIFIED` | Private `#with_store(mode, run, resolve, reject)` that opens the transaction, hands the object store to `run`, and wires `complete`/`abort` on the transaction for writes. `remove`/`store` share the write path; `load`/`list` share the read path. | Low effort / Low risk — `IndexedDBStorage.spec.js` exists. Fixing `remove` is a behaviour change (a correct one). |
+| 17 | **MEDIUM** | `FragmentAssembler` and `FragmentRetention` each implement the same bounded Map + FIFO-order-array cache, including a token-identical `#delete`. | `engine/network/transport/fragments/FragmentAssembler.js:95-103` (`#pending` + `#order`), `:150-154` (evict-oldest), `:286-290` (`#delete`), `:280-283` (`clear`); `engine/network/transport/fragments/FragmentRetention.js:72-80`, `:104-107`, `:189-193` (`#delete`), `:183-186` (`clear`) | `#delete(message_id) { this.#map.delete(message_id); const idx = this.#order.indexOf(message_id); if (idx >= 0) this.#order.splice(idx, 1); }` is identical in both. `if (map.size >= cap) { const oldest = order.shift(); if (oldest !== undefined) map.delete(oldest); }` is identical in both. `clear()` is identical. Both are keyed by the same `message_id` space and live side-by-side in `NetworkPeer`'s per-peer connection record (`NetworkPeer.js:674-680`). A third, structurally-similar bounded-key window is `ReliableCommandPipeline.#received_seqs`+`#received_order` (`engine/network/transport/ReliableCommandPipeline.js:150-158`, prune at `:250-256`). | `UNJUSTIFIED` | Promote a `BoundedFifoMap` (or `KeyedFifoCache`) to `core/collection/map/` with `set`, `get`, `delete`, `evict_oldest`, `peek_oldest`, `clear`. All three compose it; per-entry TTL/retry policy stays in the callers. | Low effort / Low risk. |
+| 18 | **MEDIUM / PROMOTION** | Four independent implementations of "per-key monotonic frame watermark map". | `engine/network/state/Baseline.js:16-83` (whole class, `Map<peer,frame>` + monotonic `set_acked`); `engine/network/replication/Replicator.js:104,244,305,322` (`#applied_through` `Map<peer,frame>`); `engine/network/orchestrator/ServerAuthoritativeServer.js:214,238-241,413-418` (`#peer_max_received_frame` `Map<peer,frame>`); `engine/network/orchestrator/ServerAuthoritativeClient.js:52,340-341` (`#last_reconciled_frame`, a `Uint32Map`) | All four store "highest frame seen for key K", all four do the same `const prev = map.get(k); if (prev === undefined || v > prev) map.set(k, v)` guard (or its inline equivalent), and all four need the same "-1 when absent" read and a `forget(key)` on disconnect. `Baseline` is literally that class and already lives in `engine/network/state/`. The backing store choice is also inconsistent (three plain `Map`, one `core/collection/Uint32Map`) with no stated reason. `Replicator.forget_peer` (`:320`) and `Baseline.forget` (`:62`) are the same method written twice. | `UNJUSTIFIED` | Reuse `Baseline` (or rename it `FrameWatermarkMap` and keep `Baseline` as an alias — meep is a library) for all four. Settle on `Uint32Map` for the integer-keyed cases. | Low effort / Low risk — `Baseline` has a spec; the other three have orchestrator-level coverage. |
+| 19 | **LOW** | `Uint8Array`/`TextEncoder` length-prefixed blob framing hand-rolled at 4 sites while a correct primitive exists in one. | primitive: `engine/ecs/storage/binary/object-v2/objectStringCodec.js:29-48`; re-derived: `engine/network/orchestrator/NetworkPeer.js:1150-1156` + `:607-615` (DISCONNECT label, `uint8` length + `TextEncoder`/`TextDecoder`), `engine/network/diagnostics/ReplayLog.js:110-113` + `:129-132` (`uvar` length + bytes), `engine/network/NetworkSession.js:1287-1300` (`ReplaceComponentAction` `uint32` length + bytes) | `writeObjectString`/`readObjectString` is exactly the "byte-length-prefixed, NUL-safe" codec, and its docblock (`objectStringCodec.js:3-8`) explains why `BinaryBuffer.writeUTF8String` cannot be used for arbitrary data. It is buried inside `object-v2` and invisible to `engine/network`, which reinvented it (with a silent 255-byte truncation at `NetworkPeer.js:1151`). Three length-prefix widths in use (`uint8`, `uvar`, `uint32`) with no shared convention. | `PROMOTION` | Move `writeObjectString`/`readObjectString` to `core/binary/` as `binary_write_string_prefixed` / `binary_read_string_prefixed` (+ a `bytes` sibling), re-export from `object-v2` for compatibility. `NetworkPeer.send_disconnect`/dispatch use it. | Low effort / Low risk. |
+| 20 | **LOW** | `SmoothingState` inlines two existing core primitives verbatim. | `engine/network/sim/SmoothingState.js:132-137` (quaternion multiply-by-conjugate); `engine/network/sim/SmoothingState.js:155` (`Math.sqrt(ex*ex + ey*ey + ez*ez)`) | Lines 134-137 are the *identical four expressions* as `core/geom/3d/quaternion/quat3_multiply.js:27-30` (`aw*bx + ax*bw + ay*bz - az*by`, …), just with the second operand pre-conjugated at `:133`. Line 155 re-derives `core/geom/vec3/v3_length.js` (mechanical brief F, `inline_length3`). Both primitives exist, are tested (`quat3_multiply.spec.js`), and this is cold code (once per corrected entity per frame). | `UNJUSTIFIED` | `quat3_multiply(s.orientation_error, 0, px,py,pz,pw, -qx,-qy,-qz,qw)` and `v3_length(ex,ey,ez)`. | Trivial effort / Low risk. |
+| 21 | **LOW** | Two inline fixed-size sample rings with full-window scans, while `core/collection/RingBuffer.js` and `array_compute_min_max` exist. | `engine/network/time/AdaptiveRenderDelay.js:124-128` (`#lateness` Float64Array + `#index` + `#filled`), scan at `:183-189`; `engine/network/time/TimeSync.js:51-64` (`#rtt_samples`/`#offset_samples` + `#sample_cursor`), scan at `:106-116` | Both: fixed `Float64Array`, cursor `(i + 1) % capacity`, then an O(n) pass over the whole window to find an extreme. `AdaptiveRenderDelay`'s min/max pass is `core/collection/array/array_compute_min_max`. `TimeSync`'s is an argmin over one array with a parallel array read — genuinely needs the paired index, so `array_compute_min` doesn't fit. | `AdaptiveRenderDelay`: `UNJUSTIFIED` (use `array_compute_min_max`). `TimeSync`: `JUSTIFIED (paired argmin over two parallel arrays; no core primitive matches)` | Swap the `AdaptiveRenderDelay` scan for `array_compute_min_max`. Leave the ring storage alone — both are perf-shaped fixed typed arrays and `RingBuffer` is an object-slot ring. | Trivial effort / Low risk. |
+| 22 | **LOW** | `#grow_*` typed-array doubling written twice, token-identical. | `engine/network/replication/Replicator.js:404-409` `#grow_record_bounds`; `engine/network/sim/RewindEngine.js:176-181` `#grow_record_starts` | `const old = this.#x; const next = new Int32Array(old.length * 2); next.set(old); this.#x = next;` — identical in both files, and these are the only two `old.length * 2` grow sites in `engine/`+`core/`. | `UNJUSTIFIED` | `core/collection/array/typed/typed_array_grow(array, min_length)` returning the (possibly same) array. Also usable by `ReplicationSlotTable.#grow` (`engine/network/state/ReplicationSlotTable.js:198-210`), which does the same with two arrays and a `fill(-1)`. | Trivial effort / Low risk. |
+| 23 | **LOW** | `seq16_advance` bypassed for an inline `& 0xFFFF`. | `engine/network/orchestrator/NetworkPeer.js:917` (`this.#next_fragment_message_id = (this.#next_fragment_message_id + 1) & 0xFFFF;`) vs `engine/network/core/sequence/seq16.js:67` `seq16_advance` | The `seq16` module is the single home for 16-bit modular sequence arithmetic and is used correctly by `Channel.js:167`. This one site open-codes it. Cosmetic today, but the whole point of the module is that every wrap-safe operation goes through it. | `UNJUSTIFIED` | `seq16_advance(this.#next_fragment_message_id)`. | Trivial effort / Trivial risk. |
+| 24 | **LOW** | `Storage`'s promise wrappers are re-derived by its own consumer instead of being used. | `engine/save/Storage.js:36-40,49-53,76-78,95-97,117-119` (`promiseLoadBinary`, `promiseStoreBinary`, `promiseList`, `promiseRemove`, `promiseContains`); `engine/save/StorageBackedList.js:88-90` and `:132-134` | `StorageBackedSet` writes `new Promise((resolve, reject) => this.storage.store(this.key, list, resolve, reject, noop))` twice, and a 3-level callback pyramid at `:47-68` for read — while `Storage` already exposes `promiseStoreBinary`/`promiseLoadBinary`/`promiseContains`. The two hand-written copies are already inconsistent (`:89` passes `noop` for `progress`, `:133` omits it). `Storage` has `promiseStoreBinary` but no `promiseStore`, which is presumably why the consumer gave up. | `UNJUSTIFIED` | Add `promiseStore`/`promiseLoad` alongside the existing `promiseStoreBinary`/`promiseLoadBinary` in `Storage`, and have `StorageBackedSet` use them. | Trivial effort / Low risk. |
+| 25 | **LOW** | "What is this class's serialized name?" resolved by 5 different rules across the serialization layer. | `engine/ecs/storage/binary/object-v2/BinaryObjectSerializer.js:269-272`; `engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter.js:59-67`; `engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter2.js:324-337`; `engine/ecs/storage/binary/BinarySerializationRegistry.js:57-67`; `engine/ecs/storage/BinaryBufferSerializer.js:140-144` | object-v2 does `registry.getClassName(ctor)` then an **own-property** `typeName` check (guarding against a subclass inheriting its ancestor's `typeName`); v1 does a bare `Object.getPrototypeOf(object).constructor.typeName` (walks the prototype chain — the divergence is already logged in `src/REVIEW_2026_08_06/engine-ecs.md:665-669`); Adapter2 does `class_registry.findNamesByModule(ctor)` with a `ctor.typeName` fallback; the registry and `BinaryBufferSerializer` each do their own bare `typeName` read with different error text. | `UNJUSTIFIED` | One `binary_resolve_type_name(registry, ctor)` in `engine/ecs/storage/binary/` implementing object-v2's (correct) rule. All five sites call it. | Low effort / Low risk. |
+
+## Serialization surface census
+
+"Would a field change need editing here?" = if you add/remove/reorder a field on the type, must this site be edited by hand?
+
+### `Transform` (`engine/ecs/transform/Transform.js`)
+
+| # | Encoding | Path | Layout | Field change needs edit? |
+|---|---|---|---|---|
+| 1 | JSON | `engine/ecs/transform/Transform.js:252` `toJSON` / `:226` `fromJSON` | `{position, rotation, scale}` delegating to the value types' own `toJSON` | **Yes** |
+| 2 | Save-game binary | `engine/ecs/transform/TransformSerializationAdapter.js:18` / `:45` | 3×Float64 pos, uint32 packed quat, equality-encoded scale | **Yes** |
+| 3 | Network wire binary | `engine/network/adapters/TransformReplicationAdapter.js:45` / `:69` | 3×Float32 pos, uint32 packed quat, equality-encoded scale | **Yes** |
+| 4 | Network wire binary (read+write, *third* copy of layout #3) | `engine/network/adapters/TransformInterpolationAdapter.js:29` `interpolate` | reads #3 twice, writes #3 once | **Yes** — and silently, with no error |
+| 5 | Local interpolation binary | `engine/interpolation/TransformPoseSerializationAdapter.js:30` / `:46` | 7×Float64 (pos + quat, no scale) | **Yes** |
+| 6 | object-v2 reflection | `engine/ecs/storage/binary/object-v2/BinaryObjectSerializer.js:309` `#writeReflected` via `Object.keys` | own enumerable fields incl. `matrix`, `flags` | No (reflective) — but produces a *different* field set than 1–5 |
+
+**5 hand-written encodings of one type.** #2/#3/#4 share a field order that nothing enforces.
+
+### `Vector3` (`core/geom/Vector3.js`)
+
+| # | Encoding | Path | Field change needs edit? |
+|---|---|---|---|
+| 1 | JSON | `core/geom/Vector3.js:1014` / `:1026` | Yes |
+| 2 | Float64 binary (`@deprecated`) | `core/geom/Vector3.js:1044` / `:1055` | Yes |
+| 3 | Float32 binary (`@deprecated`) | `core/geom/Vector3.js:1068` / `:1079` | Yes |
+| 4 | Equality-compressed binary | `core/geom/vec3/serialization/v3_binary_equality_encode.js` / `_decode.js` | Yes |
+| 5 | Float32 interpolation | `engine/network/adapters/Vector3InterpolationAdapter.js:27` | Yes |
+| 6–14 | 9 inline open-codings inside component adapters | `TransformSerializationAdapter.js:24`, `TransformPoseSerializationAdapter.js:33`, `TransformReplicationAdapter.js:51`, `RigidBodySerializationAdapter.js:33,37,43`, `JointSerializationAdapter.js:30-31`, `TopDownCameraControllerSerializationAdapter.js:16`, `GamepadStickCalibration.js:101`, `PathSerializationAdapter.js:30`, `TerrainSerializationAdapter.js:37,40,90` | Yes, each |
+
+**~14 independent encodings.** Only #4 is a shared primitive with a spec.
+
+### `Quaternion` (`core/geom/Quaternion.js`)
+
+| # | Encoding | Path | Field change needs edit? |
+|---|---|---|---|
+| 1 | JSON | `core/geom/Quaternion.js:1345` / `:1359` | Yes |
+| 2 | Float64 binary | `core/geom/Quaternion.js:1367` / `:1378` | Yes |
+| 3 | Float32 binary | `core/geom/Quaternion.js:1391` / `:1402` | Yes |
+| 4 | Smallest-three uint32 | `core/geom/3d/quaternion/quat3_encode_to_uint32.js` / `quat3_decode_from_uint32.js` (alias files `quat_*` re-export) | Yes |
+| 5 | Float32 interpolation | `engine/network/adapters/QuaternionInterpolationAdapter.js:14` | Yes |
+| 6 | Inline in Transform pose adapter | `engine/interpolation/TransformPoseSerializationAdapter.js:36-39,51-53` | Yes |
+
+### `Vector4` / `Vector2` / `Vector1` / `Color`
+
+| Type | Encodings | Paths |
+|---|---|---|
+| `Vector4` | JSON + Float64 binary | `core/geom/Vector4.js:437`/`:446`, `:454`/`:465` |
+| `Vector2` | JSON + Float64 binary + Float32 binary | `core/geom/Vector2.js:422`/`:426`, `:439`/`:448`, `:459`/`:468` |
+| `Vector1` | JSON + Float64 binary | `core/geom/Vector1.js:270`/`:278` |
+| `Color` | JSON + Float32 binary (`@deprecated`) + CSS-string `parse` | `core/color/Color.js:571`/`:567`, `:642`/`:653`, `:664` |
+
+`Vector4.fromBinaryBuffer` (`:465`) and `Quaternion.fromBinaryBuffer` (`:1378`) are **literally identical** (4× `readFloat64` + `set`); `Color.fromBinaryBuffer` (`:653`) is the same shape at Float32. See dismissed leads — this one is justified.
+
+### `NetworkIdentity` (the only ECS component with a *single* encoding)
+
+| # | Encoding | Path |
+|---|---|---|
+| 1 | Save-game binary | `engine/network/ecs/serialization/NetworkIdentitySerializationAdapter.js:36` / `:59` |
+
+Deliberately never on the wire (`:19-22`) — the counter-example that shows one encoding is achievable when the design says so.
+
+### Summary
+
+`Transform` has **5** hand-maintained binary/JSON encodings, `Vector3` ~**14**, `Quaternion` **6**. A field-layout change to `Transform` requires 5 coordinated edits, **none of which is enforced by a type, an assert, or a shared test**; the `TransformReplicationAdapter` ⟷ `TransformInterpolationAdapter` pair (#3/#4) is coupled by a prose comment only, and a mismatch there corrupts every interpolated remote entity with no error.
+
+## Dismissed leads
+
+- **`Color.fromBinaryBuffer` / `Quaternion.fromBinaryBuffer` / `Vector4.fromBinaryBuffer` token-identical (mechanical brief A).** JUSTIFIED: 5-line leaf codecs; a `read_float_tuple(buffer, n, precision)` primitive would need a precision selector (Color is f32, the others f64) — a sentinel parameter the house rules reject — and adds a call layer to the lowest-level codec for no maintenance win. The *real* problem is finding #3 (no shared vector codec used by adapters), not these methods.
+- **`seq16.js` vs `seq32.js` (near-identical API and `greater_than` body).** JUSTIFIED: `seq32_greater_than`/`seq32_distance` must use Number arithmetic because JS bitwise operators sign-extend at bit 31 (documented at `seq32.js:36-38`); a shared implementation would be wrong for one of them. Separately noted: `seq32_*` has **no production callers** (only its own spec) — library surface, not dead code, so leave it.
+- **Hand-written per-class `BinaryClassSerializationAdapter` subclasses looking alike.** JUSTIFIED by explicit design bet (action-log replication with hand-written adapters). The duplication that *is* worth fixing is the missing value-type codec primitives underneath them (#3), not the adapters.
+- **`BinaryObjectSerializer.writeValue` vs `BinaryObjectDeSerializer.readValue`, `serialize` vs `deserialize`, `snapshotter_emit` vs `snapshotter_apply`.** JUSTIFIED: encode/decode pairs are inherently mirrored; the format constants are already shared via `ObjectBinaryFormat.js` (which is why the mechanical brief flagged the import block, not the logic).
+- **`BinaryCollectionSerializer.setRegistry`/`setBuffer` vs `BinaryCollectionDeSerializer.setRegistry`/`setBuffer`; `BinaryObjectSerializer.setRegistry` vs `BinaryObjectDeSerializer.setRegistry`.** 4-line assertion setters. Too small; a shared base class would be ceremony.
+- **`SimActionRegistry` vs `ReplicatedComponentRegistry` "assign a sequential uint8 type_id, cap at 256".** ~6 shared lines inside otherwise-unrelated classes (one owns an object pool, the other an adapter cache). Not worth a shared base.
+- **`SimActionRegistry`'s per-type object pool vs `core/model/object/ObjectPoolFactory`.** Checked: the registry pool is a `SimAction[][]` indexed by `type_id` with `reset()`-on-acquire; `ObjectPoolFactory` is per-class with a factory callback. Swapping would need one factory per action class registered at `register()` time. Marginal.
+- **`ReplicationSlotTable`'s free-list + highwater vs `core/IdPool`.** Checked `core/IdPool.js`: it is `BitSet`-backed with `nextClearBit` allocation (lowest-free-first). `ReplicationSlotTable` needs LIFO recycling *plus* a per-slot generation counter *plus* the reverse `entity→network` map, and deliberately keeps ids dense in a typed array. Different enough.
+- **`JitterBuffer.push` sorted-insert vs `ServerAuthoritativeServer.#track_referenced_frame` sorted-insert.** Both already use `core/collection/array/binarySearchHighIndex` — this is reuse working correctly, not duplication.
+- **`SimulatedTransport`'s linear insertion-sort into `in_queue` (`:163-166`) vs `JitterBuffer`.** SimulatedTransport is a test/prototype link simulator; the insert is O(n) by design for tiny queues. Cold code, different key.
+- **`SyncTest.__fnv_byte` (`engine/network/diagnostics/SyncTest.js:58`) vs `core/collection/array/typed/uint8_array_hash`.** Checked both: the core hash is a DJB-style word-at-a-time hash with no incremental accumulator, while `fingerprint_world` must interleave entity_id and type_id bytes between component payloads. Not a drop-in. Noted, not filed.
+- **`ScopeFilter` / `owner_authorization` / `ChangedEntitySet` / `PriorityAccumulator` / `MutationLedger` / `TimeDilation`.** Read; no duplication found.
+
+## Notes — why duplication accumulates here
+
+1. **Wire formats are documented, not typed.** `ActionLog.js:10-22`, `Replicator.js:26-35`, `Snapshotter.js:19-29`, `Channel.js:9-16`, `fragment_send.js:12-21`, `TransformReplicationAdapter.js:23-28` all describe their byte layout in a docblock and then hand-write the reader and writer separately. Nothing in the language couples them, so every new consumer of a format writes a fresh parser (finding #1: five parsers for one format). The one place this was done right — `ObjectBinaryFormat.js` as a shared constants module — is exactly the place the mechanical pass found *no* logic duplication.
+
+2. **Three generations of object serializer were built without retiring the previous one.** v1 (`object/BinaryObjectSerializationAdapter`) is wired; v2 (`object/BinaryObjectSerializationAdapter2`) has zero importers; v3 (`object-v2/`) has a README, a DESIGN.md, four spec files, and zero production consumers. Each generation re-derived the primitive-tag switch and the interning table from scratch rather than extending its predecessor. "meep is a library, unreferenced exports are public surface" protects v3 (documented, spec'd, intended to be used) but not v2 (undocumented intermediate with no spec).
+
+3. **`Transport.js` was written as a base class but only used as an interface.** It has default `getStats`, `connect`, `disconnect` implementations (`:95-111`), and six subclasses that override all three with copies of each other rather than calling up. The `#disconnect_fired` latch was invented three times independently — and forgotten on the fourth adapter (`WebTransportTransport`), which is now behaviourally inconsistent.
+
+4. **`core/` primitives are hard to discover from `engine/network/`.** `quat3_multiply` is inlined verbatim in `SmoothingState.js` with a comment saying the helper doesn't exist; `lerp` is used in one interpolation adapter and inlined 14× in the other two; `v3_length` is inlined; `objectStringCodec`'s length-prefixed codec is reinvented in `NetworkPeer`. There is a real gap too — no `quat3_nlerp` exists anywhere — but three of the four cases are pure discovery failure.
+
+5. **Parallel-array containers invite copy-paste compaction.** `ServerAuthoritativeServer`'s four `#pending_*` arrays forced two 19-line compaction methods (#10) and two dedup triple-comparison loops (`:454-459` and `:567-572`). `core/collection/table/RowFirstTable` exists for exactly this and is not used here — worth considering if a fifth column is ever added.
+
+6. **One real correctness consequence, already latent.** Finding #16 (`IndexedDBStorage.remove` never got the transaction-durability fix that `store` did) and finding #4 (AUTH_STATE writer/reader skip on different predicates) are both live divergences produced by this pattern, not hypotheticals.
+
+7. **Out of scope but noted (house rule: don't silently catch).** `engine/network/orchestrator/ServerAuthoritativeClient.js:379-386` wraps `rewind_engine.rewind_to` in a `try { … } catch (e) { return; }` that swallows every error, not just the anticipated "log rolled past server_frame". `engine/save/storage/IndexedDBStorage.js:120-125` (`get_bound_address`-style `catch → return null`) and `WebTransportTransport.js:148-155` (three `catch (_) { /* swallow */ }`) are the same shape. Separate concern from duplication.