@woosh/meep-engine 3.60.3 → 3.60.5

package/src/engine/network/SMOOTHNESS_DESIGN.md

@@ -1,400 +0,0 @@
-# Perceptual smoothness — design and plan
-
-**Status:** implemented on `feature/network-smoothness` (phases 1–7 below). §6 records what the
-implementation found that this plan did not foresee, §7 the measured result, §8 what is left.
-**Goal:** a game that wires `NetworkSession` the obvious way renders smoothly out of the box — its
-own predicted entities, other players' entities, and the host's view of everybody — at any display
-rate, without the game knowing what `Interpolated`, `InterpolationLog` or `SmoothingState` are.
-
-Three projects built on this package ended up with jerky motion by default, each time with an
-agent that had been pointed at the interpolation package. Each piece is correct and tested on its
-own; nothing tests or documents what happens when physics, the network and interpolation all drive
-one entity. This note records what goes wrong there, the design that fixes it, and the order the
-work lands in.
-
----
-
-## 1. What is wrong today
-
-Verified means there is a failing spec or a trace; read means it follows from the code and is
-covered by a spec written in the phase that fixes it.
-
-| # | Defect | Evidence |
-|---|---|---|
-| D1 | **Network writes to `Transform64` are never announced.** `ReplaceComponentAction.apply`, AUTH_STATE apply, rewind restore, the session's render blend and `normalize_if_dirty` all write through `adapter.deserialize` and nobody calls `t64_announce_change`. Mesh placement (`ShadedGeometrySystem`, `MeshSystem`) and the attachment sync only react to `TRANSFORM64_EVENT_CHANGE`, so a networked pose can change without the mesh moving. | read (Transform64 migration landed after the network code) |
-| D2 | **An interpolated body throws away every correction.** `PhysicsSystem.__interp_restore` opens each step by restoring interpolated bodies from the log's previous tick. The log holds the client's own prediction; the correction went to the live `Transform64` only. | **verified** — `predicted_body_correction.spec.js`: the drawn ball stays 0.5 m off through 30 ticks of corrections; the same scenario without `Interpolated` converges |
-| D3 | **Two clocks.** `NetworkSession.tick` runs its own accumulator; `EntityManager` runs another. Network frame N and `fixedStepTick` are unrelated counters, so the interpolation alpha of one is meaningless to the other. | read |
-| D4 | **Time dilation drops or doubles whole ticks.** `#local_frame_accum += 1/dilation` quantises a ≤5% rate change into a skipped or doubled tick every ~20 steps. | read |
-| D5 | **Predicted entities are never interpolated.** The session skips owned entities ("predicted, not interpolated"); the physics producer only covers physics bodies that the game opted in by hand, and runs on the other clock. | read |
-| D6 | **Remote entities are blended on a private path.** The session's own `#render_interpolated_entities` runs inside `tick()`, not per render frame; it does not announce (D1); it is not ordered before the camera. `InterpolationSystem.registerSource` exists for exactly this and is never called. | read |
-| D7 | **`InterpolationSystem` runs after `CameraSystem`.** It declares only `Interpolated`, so its derived order puts it after every system that reads `Transform64` — a camera that follows an interpolated entity copies last frame's pose. | read (ordering arithmetic) |
-| D8 | **Every AUTH_STATE rewinds, and corrections are stale and unsmoothed.** The no-op short-circuit needs `onComputeExpected`/`onMeasureCurrent`, which the session never wires. Replay re-executes input actions only, never the fixed-step systems, so a physics-driven entity is set to the server's *past* pose and left there. `SmoothingState` exists but is not wired. | verified (trace: control case lands one step behind the host, not ahead) |
-| D9 | **Physics-driven state reaches remote peers only if the game publishes it by hand**, every tick, from the right hook. Publishing through `net_mutate_component` also writes the quantised wire value back into the host's own live state, so the host's physics continues from a 10-bit-per-component rotation every tick. | read |
-| D10 | **A frame with no actions is a hole in the remote log.** The playout blends `(floor, floor+1)`; a missing endpoint snaps to the other, and a window with both missing leaves the live value — the *newest* truth — so an entity jumps ahead and then holds. | read |
-| D11 | `setPose`'s `snap` is cleared by the render pass before the next step reads it (known, documented at `PhysicsSystem.js` setPose). | read |
-| D12 | A body spawned after the physics step has no record for its birth tick (GAP-036). | documented |
-
-Adjacent, **not** in scope here (affects every game, networked or not, and belongs to the engine
-loop): `Ticker` samples the simulation dt from `setTimeout(0)` after `requestAnimationFrame`, and
-render runs before simulate, so the interpolation alpha carries scheduling jitter. Tracked as a
-follow-up.
-
----
-
-## 2. Target model
-
-**One clock.** The `EntityManager` fixed step is the network tick. Network frame N is simulated by
-exactly one EM fixed step; nothing else advances simulation time.
-
-**Every entity is in exactly one of three roles on each peer**, and each role has one smoothing path:
-
-| Role | Where | Simulated by | Rendered by |
-|---|---|---|---|
-| **Authoritative** | everything on the host | host fixed step (inputs + systems) | local fixed-step interpolation |
-| **Predicted** | entities the client owns | client fixed step (sampled input + systems) | local fixed-step interpolation, plus a decaying visual offset after a correction |
-| **Interpolated** | everything else on a client | nobody locally — the network writes it | the network playout (render-delayed), via the same `InterpolationSystem` |
-
-**One interpolation pipeline.** `InterpolationSystem` owns render-time interpolation end to end:
-
-- **Record** (end of every fixed step): every `Interpolated` entity on the local timeline is
-  recorded into the local log. Physics no longer records; neither does anything else. This also
-  closes D12 — the record runs after every system, so a body spawned during the step is recorded
-  on its birth tick.
-- **Blend** (every render frame, before any reader of `Transform64`): local entities between the
-  last two ticks at the fixed-step alpha; network entities on the registered playout; the write is
-  announced.
-- **Restore — guarded** (start of every fixed step, and on demand before network applies): the
-  system remembers, per entity it wrote, the value it displaced and the value it wrote. It puts the
-  displaced value back **only if the live value is still the one it wrote**. Anything else that
-  wrote in between — a network correction, `setPose`, game code — is authoritative and stays. This
-  is what fixes D2 and D11 without either side knowing about the other.
-
-**Corrections are applied to history, not just to the present.** When a predicted entity is
-corrected by Δ, the local log's recent records for it are shifted by Δ too (so the blend has no
-discontinuity) and the rendered pose gets a visual offset of −Δ that decays over ~0.1–0.3 s.
-
-**Reconciliation compares before it corrects.** The client records its own predicted replicated
-state per frame. AUTH_STATE for frame S is compared with the client's prediction *for S*:
-
-- equal within tolerance → nothing happens (the common case; today it is a full rewind);
-- different → the present is corrected by the error observed at S (`present += server(S) −
-  predicted(S)` — position additive, rotation as a relative quaternion), the prediction history
-  after S is shifted by the same error, and the visual offset hides the step.
-
-This is the correction used for physics-predicted objects in shipped engines (Mirror's
-`PredictedRigidbody`, Fiedler's state-sync smoothing). It needs no re-simulation and no physics
-rollback — which does not exist in the engine (restoring physics in place would need manifold,
-sleep-group and broadphase restore; see the inventory in the review notes) and would cost
-`RTT/step` physics steps per correction. It is exact for motion that does not depend on position,
-and converges within a round trip for motion that does (a collision the correction would have
-avoided is corrected again by the next AUTH_STATE).
-
-The action-log rewind + replay path stays, as an opt-in (`reconcile: 'replay'`), for games whose
-predicted state is entirely produced by deterministic `SimAction`s and that want exactness.
-
-**Superseded 2026-10-15: the host no longer looks for changes.** What follows describes the
-end-of-step comparison as built. It cost every host tick a pass over every networked entity — 7–8 ms
-for 20,000 entities with nothing changing — and the stack is for worlds of millions. It is gone: what
-travels is what goes through the executor, actions and direct writes reported with
-`net_mutate_component`, which the host records (`executor.record`, no write-back, D9's second half
-kept fixed). A direct write nobody reports stays on the host — D9's first half is the contract now,
-stated in the README's "What the session assumes".
-
-**The host publishes what changed** (as built, superseded above). At the end of every host step, each replicated component of
-each networked entity is encoded with its replication adapter and compared with what was last
-published; changed ones go out as `ReplaceComponentAction` records. They are recorded without
-applying (the host's live state is not overwritten with its quantised wire image — D9) and
-without prior state (they are not rolled back — the physics that produced them is not rolled back
-either).
-
-**Late input is applied when it arrives, on the host, in turnkey mode.** The input buffer
-(`simulation_delay_ticks`) and time dilation keep inputs on time; an input that is late anyway is
-applied at the current simulated frame rather than by rewinding. Rewinding the host replays
-actions but not physics, so for a physics game it bought nothing and cost a replay. The rollback
-path stays for `ServerAuthoritativeServer` users and for `reconcile: 'replay'` sessions.
-
----
-
-## 3. Design changes by module
-
-### `EntityManager` and `System`
-- Two system phases, `openFixedStep()` and `closeFixedStep()`, bracketing each fixed step: every
-  system that has them is opened, in execution order, before any `fixedUpdate`, and closed in
-  reverse after the last; a system whose open throws is not closed. They are what a step's framing
-  needs and no more — the interpolation system settles in one, the network opens and closes its
-  frame in the pair — and they are part of the system contract, ordered like everything else.
-  (The first cut added `onFixedStepBegin` / `onFixedStepEnd` signals on the `EntityManager`: an
-  open subscription point on the core loop that anything could attach to, in no defined order.
-  Replaced; see §9.)
-- `fixedStepTimeScale` (default 1): wall time is scaled by it on its way into the fixed-step
-  accumulator only. Systems still receive `fixedUpdateStepSize`; the `update` pass still receives
-  the raw dt. Time dilation sets it to `1 / dilation_factor`.
-
-### `InterpolationSystem`
-- Restores when a step opens (`settle()`, also callable by a system that applies state as the step
-  opens) and on `restore()`: every value a render blend displaced is put back, and so is anything
-  written over the blend since — unless the entity declared its live value with `snap`. The truth
-  is held losslessly, through the component's `copy` where it has one.
-- Local recording of every completed step, for every `Interpolated` entity on the local timeline,
-  at the next step's open or the next render update, whichever comes first. A record made before an
-  entity was linked is not blended from (entity ids are reused).
-- Declares `Write` on `Transform64`, so derived order puts the blend before readers (D7).
-- `snap` rewrites the entity's latest records with its live pose instead of skipping one frame, so
-  the blend continues from the teleported pose (D11).
-- Visual offset per entity (position + rotation in the body's frame), decayed by frame time, applied
-  after the blend of a `Transform64` pose; `correct(entity, Δp, e)` shifts recent history and adds
-  the inverse to the offset.
-- `allocateSourceId()`; `registerSource` refuses a second registration of a live id.
-- `InterpolationLog.rewrite(tick, key, type_id, fn)` — in-place, same-length record rewrite —
-  `latest_tick_at_or_before(tick)` and `ensure_ticks(n)`.
-
-### `PhysicsSystem`
-- No longer restores or records. `interpolationLog` is kept as a deprecated field that warns once;
-  the `InterpolationSystem` produces the same (better) result with no wiring.
-
-### `NetworkSession`
-- Driven by the EM through its `NetworkSystem`, given a driver: the network frame opens in
-  `openFixedStep` and closes in `closeFixedStep`; frame-paced duties (reconnect ladder, liveness,
-  grace, the playout's clock) run in `update`, on the engine's frame time. `tick(dt)` is deprecated:
-  it warns once and does nothing. `tick_rate_hz`, when given, sets the EM step.
-- Inbound traffic is held (`DeferredTransport`) and applied as the step opens, after
-  `interpolation.settle()` — never between a frame's blend and its draw (§9, finding 1).
-- Requires an `InterpolationSystem` and adds one if the EM has none. Attaches (or adapts) an
-  `Interpolated` on every networked entity, by role; re-evaluates on ownership change.
-- Replication says how each component is drawn, with no optional parameters:
-  `replicate_interpolated(C, interpoland)` blends it, `replicate_discrete(C)` shows each state as it
-  lands. The session names no component type in its API; `replicate_transform64(session)`, in
-  `network/adapters` beside the Transform64 wire adapter, is `replicate_interpolated(Transform64,
-  POSE_INTERPOLAND)` — the pose blended at full precision (7 doubles), not re-quantised through the
-  wire layout.
-- Remote entities are blended by `InterpolationSystem` on a registered network source whose window
-  holds across frames that carried no change (D10). `normalize_if_dirty` delegates to `restore()`.
-- Every write it makes to a replicated component in place is announced (D1), through the
-  component's replication adapter (`announce(dataset, entity)`); the Transform64 adapter announces
-  a Transform64. The network itself knows no component that needs it.
-- Client: AUTH_STATE is queued (newest per entity, none older than the last reconciled) and
-  reconciled as the next step opens, using the comparison + correction above. The session compares
-  wire images and hands a component that differs to its `Correction` — `same`, `carry` (into each
-  prediction since S), `apply` (to the live component, and through whatever owns it) — so it knows
-  no component type, and no physics. `POSE_CORRECTION` (Transform64, through physics for a body,
-  hidden by `InterpolationSystem.correct`), `VELOCITY_CORRECTION` and `HOST_VALUE_CORRECTION` are
-  given. `reconcile: 'correct' | 'replay'`, default `'correct'`.
-- Host: ~~publishes changed replicated state at the end of each step~~ (removed 2026-10-15: what
-  travels is what goes through the executor; a reported direct write is recorded, not executed);
-  `late_input: 'apply' | 'rollback'`, default `'apply'`.
-
-### Orchestrators
-- `ServerAuthoritativeServer`: `begin_tick(frame)` / `end_tick()` split, so the EM's systems run
-  inside the open frame; `tick(frame)` remains as begin+end. `late_input` option.
-- `ServerAuthoritativeClient`: `begin_tick`/`end_tick` split; `auto_reconcile` option so the session
-  can take AUTH_STATE over.
-- `SimActionExecutor.record(action)`: log a record without applying it and without prior state (for
-  host publishing), stamped `SENDER_RECORDED`; a rollback replay carries it over unchanged.
-- `SimActionExecutor.execute` is transactional: an action whose `apply` throws is undone from the
-  prior state it captured and leaves no record; announcements follow the completed record.
-
----
-
-## 4. Compatibility
-
-- `NetworkSession.tick(dt)` → no-op + one-time warning. Call `entity_manager.update(dt)` (the engine
-  loop already does). **Breaking** for code that drove the session without an EM loop.
-- Default reconcile changes from rewind+replay to compare+correct; `reconcile: 'replay'` restores
-  the old behaviour. Default host late-input handling changes from rollback to apply;
-  `late_input: 'rollback'` restores it.
-- `replicate()` is deprecated in favour of `replicate_interpolated(C, interpoland)` and
-  `replicate_discrete(C)`. It keeps its meaning — `replicate(C)` is discrete, `replicate(C, adapter)`
-  blended over the component's replication layout, `Transform64` included — and warns once. **Breaking** only where it blends a component
-  without `copy(other)`, which is now required of any component blended between ticks.
-- Inbound traffic takes effect at the receiver's next fixed step; the session's timers follow the
-  engine's frame time. Code that delivered packets by hand and read the result at once must step.
-- An interpolated entity written between steps without `snap` or a prior `restore()` is put back at
-  the next step. This was the rule for interpolated physics bodies already; it now holds for every
-  `Interpolated` entity. **Behaviour change** for code that relied on the old absence of any restore
-  for non-physics entities.
-- Peer ids are `[0, 251]`; 252 is `SENDER_CORRECTED`, 253 is `SENDER_RECORDED`.
-- `PhysicsSystem.interpolationLog` is deprecated (ignored, warns once).
-- Wire format: a new `FRAME_MARKER` packet; nothing else.
-- `scene-editor`'s `RemotePresence` (the only in-repo `registerSource` user) needed one change: a
-  drag's end — a committed record, the canonical bytes written back — now declares the entity's live
-  value with `snap` before taking its `Interpolated` away, where it used to rely on nothing restoring.
-  Its spec caught it.
-
----
-
-## 5. Phases
-
-Each phase lands as its own commit(s) with its specs, and leaves the tree green.
-
-1. **EM hooks** — signals + time scale. Specs: order of begin/fixedUpdate/end; time scale changes step
-   cadence, not step size. (The signals became system phases after review — §9.)
-2. **InterpolationSystem owns interpolation** — guarded restore (an unconditional one after
-   review — §9), local record, write-ordering,
-   snap-by-rewrite, visual offset + `correct()`, log rewrite; physics producer retired; physics
-   interpolation specs ported. `predicted_body_correction.spec.js` goes green here.
-3. **One clock for the session** — orchestrator begin/end split, EM-driven session, dilation through
-   the time scale, remote entities through a registered source with hold-across-gaps, auto
-   `Interpolated`, announcements. Existing session specs migrate from `session.tick` to
-   `em.update`.
-4. **Host publishes** — `executor.record`, change detection, no write-back; late input applied.
-5. **Client reconciles by comparison** — prediction history, queued AUTH_STATE, correct + shift +
-   visual offset; `'replay'` kept and tested.
-6. **Render-cadence spec** — host + clients over a jittery simulated link, rendered at 144 Hz on a
-   60 Hz step: per-frame displacement of a constant-velocity entity is near-constant for the
-   predicted, remote and host views alike. This is the "turnkey" acceptance test.
-7. **Docs** — README section "Smooth by default", CHANGELOG, migration notes.
-
-Deferred (named, not started): predicted non-owned entities (a Rocket League–style shared ball
-predicted by every client), automatic kinematic proxies for remote physics bodies, and the engine-loop dt jitter above.
-
----
-
-## 6. Found during implementation
-
-Each of these surfaced as a failing or wrongly-passing spec, and each is fixed on the branch.
-
-- **The repro first passed for the wrong reason.** Sampled right after packet delivery, it read
-  the correction in the one window where it existed. Sampled where the renderer reads — after the
-  update, before the next packets — it showed the ball 0.5 m off for good. Specs here measure what
-  is drawn.
-- **A client echoed the host's state back to the host every tick.** Arrived records are logged, and
-  a peer's outbound stream repacks its log for every peer. For host-owned entities ownership rejects
-  the echo; for client-owned ones the host applied it as input and overwrote its own simulation —
-  the host's copy of a client-owned ball dropped a step every fifth frame. The replicator now never
-  sends a record back to its sender.
-- **A record with no prior state is out of scope-filter reach.** The filter reads a record's
-  prior-state entries to find its entities; the host's published records had none and went to
-  everyone, owner included. They now carry empty entries that name the entity; rewind skips them.
-- **Time dilation ran away for clients without input.** Buffer depth was measured from received
-  input only, so a client sending none read as depth 0 and was told to run 5% fast forever. The
-  per-tick keep-alive is now a `FRAME_MARKER` carrying the client's frame.
-- **The playout started one frame behind the stream.** With less than a delay's worth of frames at
-  the first sample the playhead was clamped to 0, and the deliberately slow pull took seconds to
-  open the gap. It now waits for a whole delay before it starts.
-- **Publishing had to follow the local sim.** Recording at step end, before `onLocalSim`, published
-  what an `onLocalSim` action was about to overwrite. The server gained `onBeforeTickClose`.
-- **The local log could not hold two ticks of a large world.** Recording every interpolated entity
-  every tick outgrew 64 KB at ~1000 entities, and a blend missing its older tick snaps.
-  `InterpolationLog.ensure_ticks` grows it in place.
-
-## 7. Result
-
-`NetworkSession.smoothness.spec.js`: a host and a client, 144 Hz render, 60 Hz step, each frame run
-in a browser's order — the engine updates, then the network delivers, then the frame is drawn. A
-*hitch* is a drawn frame that moves less than half or more than one and a half of the typical
-per-frame travel. Measured on this branch and, with the same scenario wired as the old docs led
-(session `tick` next to `em.update`, the Transform interpolator, the NPC published from
-`onLocalSim`, `Interpolated` on the entities), on the tree before it:
-
-| view (719 drawn frames) | before, clean link | after, clean link | after, 45±20 ms, 5% loss |
-|---|---|---|---|
-| client's predicted player | 719 hitches, 420 frames frozen | 0 (worst 1.2%) | 0 (worst 6%) |
-| host NPC, drawn on the client | 240 hitches | 0 (worst 0.9%) | 0 (worst 2.5%) |
-| host's view of the client's player | 719 hitches | 0 | 0 on this link's seed; input later than the buffer shows as a hitch (§8) |
-| host's own NPC | 719 hitches | 0 | 0 |
-
-With inbound traffic applied on arrival instead of at the step (the order a browser delivers it),
-the same spec fails on the clean link — its worst frame moves 83% off the typical one — and shows
-319 hitches on the lossy one.
-
-## 8. What is left
-
-- **The host's view of late input.** The host draws its authoritative simulation; input later than
-  the buffer shows as a stall then a double step. Remedies, in rising cost: a larger
-  `simulation_delay_ticks`; an input buffer that adapts to observed lateness; repeating a client's
-  last input when one is missing and reconciling when it lands.
-- **Predicted non-owned entities** — a shared ball every client predicts — need AUTH_STATE for
-  entities a peer does not own, and a per-entity choice between predicted and played out.
-- **Ownership handoff.** An entity that changes hands moves between the local timeline and the
-  playout, a render delay apart, and jumps when it does.
-- **Automatic kinematic proxies** for remote physics bodies. A client that gives a remote entity a
-  dynamic body has two writers fighting over its pose, and nothing says so: the session knows no
-  physics to check with.
-- **Engine-loop timing.** `Ticker` samples the frame delta in a `setTimeout(0)` after the animation
-  frame, and draws before it simulates; the interpolation alpha carries that scheduling jitter. It
-  affects every game, networked or not, and belongs to its own change.
-- **Correction across components.** A strategy corrects its own component. A velocity corrected at
-  S is not carried into the positions predicted since S; the pose's own correction takes that up, a
-  frame at a time, as the host's states arrive. And `HOST_VALUE_CORRECTION` drops what a client
-  predicted since S, so it never settles for a component the client predicts from its input — such
-  a component needs a strategy that carries its difference.
-- **A write between steps that forgets to say so** is put back without a word. The engine cannot
-  tell it from a render-phase writer reacting to the blend, which must be put back; a debug-build
-  warning, or a small `teleport()` helper, would make the rule harder to miss.
-- **A paused engine holds its session's traffic.** Packets wait for the next step; an engine
-  stopped for long with its session still connected holds them all, and the peer reaps it anyway.
-
-## 9. Independent review, and three corrections
-
-The branch was reviewed independently once the first cut was green. Twelve findings, all real:
-
-| # | Finding | Fix |
-|---|---|---|
-| 1 | Packets are handled between a frame's blend and its draw; applying them restores the truth for everything blended, so most client frames drew unblended | Inbound traffic is held (`DeferredTransport`) and applied as the next step opens, after the interpolation system settles. The acceptance spec now runs frames in browser order |
-| 2 | An AUTH_STATE arriving after a newer one corrected the present a second time | The newest reconciled frame per network id; older states are dropped |
-| 3 | Skipping components an action wrote lost a change the simulation made to them later in the step | The publish baseline is "what the peers hold", updated by every executed action; the step's end publishes any difference |
-| 4 | A resync compared new states against predictions for the world it replaced | INITIAL_SYNC clears the prediction history, pending states and sampled input |
-| 5 | Render-phase writers (`ClingToTerrainSystem`) leaked the blend into the simulation through the guarded restore | Restore always, as physics already did; a deliberate write between steps says so with `snap` or `restore()` first |
-| 6 | Restoring through a lossy wire adapter rounded the truth | The truth is a copy of the component, through its `copy()`; `replicate_interpolated` refuses a component without one |
-| 7 | `ensure_ticks` dropped bytes past the logical capacity | It copies the whole buffer |
-| 8 | A reused entity id blended from the previous owner's records | Records from before an entity's link are not blended from |
-| 9 | A rollback replay dropped the host's published records | Records carry `SENDER_RECORDED`; a replay writes them back unchanged |
-| 10 | Scale was never compared or corrected | Compared, and corrected by ratio |
-| 11 | `rewrite` before the first step mistook −1 for the open tick | Guarded |
-| 12 | Exceptions left frames open or records half-written | Transactional `execute`; announcements after the record; a failing host input is reported and skipped; a `begin_tick` that fails part-way closes the frame it opened, and the session moves on to the next frame; one entity's failed correction does not stop the others |
-
-Of the lesser notes, four were right and are fixed: a turn observed at S must be carried in the
-body's frame (`q' = q · e`), since physics integrates rotation in world space; the position
-tolerance must grow with distance from the origin, as Float32's step does; `restore()` threw away
-its per-entity slots every step (now pooled); and `PredictionHistory.get` allocated per read. Two
-are left on purpose: networked entities that carry no interpolated component are looked at again
-each step until one arrives — correct, and a handful of lookups — and queueing an AUTH_STATE
-allocates a few small objects, a few hundred a second.
-
-Finding 5 changed a design decision. The guard existed because network writes landed between
-frames; once they land in the step (finding 1), the engine's older contract — always restore, a
-deliberate write declares itself — covers everything, and the guard's leak goes with it. Its cost
-is that an undeclared write between steps is put back: the scene editor's remote-drag presence
-relied on nothing restoring, and its spec caught it.
-
-Three corrections came from the author while the findings were being fixed:
-
-- **The `EntityManager` seam was too wide.** `onFixedStepBegin` / `onFixedStepEnd` were open
-  signals on the core loop: anything could subscribe, in no defined order, and it invited bolting
-  on work that belongs in a system. They became two system phases, `openFixedStep` /
-  `closeFixedStep`, with the same ordering as every other phase and the smallest contract that
-  frames a step; `NetworkSystem` takes a driver for them.
-- **`replicate()`'s second argument meant too many things** — omitted meant "interpolate" for one
-  class and "snap" for the rest, `null` meant snap, an adapter meant "interpolate" but was ignored
-  for `Transform64`. A first pass made it an options object, which still left optional fields and a
-  default to fall into. It is now two methods with no optional parameters,
-  `replicate_interpolated(C, interpoland)` and `replicate_discrete(C)`: every call says how its
-  component is drawn. A `replicate_transform()` on the session came and went — a component type
-  named in the session's own API, coupling it to one of the things it carries. The shortcut is a
-  free function beside the Transform64 wire adapter, `replicate_transform64(session)`, and it is the
-  general call, nothing more. The same went for reconciliation: the session special-cased
-  `Transform64` and duck-typed physics to correct poses and velocities. Correction is now a strategy
-  each component is registered with, as its interpolation is; the pose and velocity strategies sit
-  beside the Transform64 wire adapter, and the physics lookup with them. Last to go: the network's
-  announcement of in-place writes named Transform64 — it now asks the component's replication
-  adapter, and the Transform64 adapter answers — and a warning for a remote entity with a dynamic
-  body needed the session to know physics. The warning was dropped: a missing message is better than
-  the session knowing what a rigid body is. The network's core — session, replication, simulation,
-  transport — names no component type and imports nothing from physics; what is specific to a
-  component lives in `network/adapters`.
-- **Specs reached behind the curtain.** Patching `performance.now` tied specs to how the engine
-  reads time — something the engine may change — and let the session run on a clock of its own. The
-  session now runs on the engine's frame time, so a spec drives time by driving the engine. Other
-  mocks went too: monkeypatched time dilation became a client that falls behind and is told to
-  catch up; spied executor calls became bytes on the wire, compared with a session that does not
-  publish; an injected retransmission became a real one; reads of the interpolation log became the
-  pose that is drawn. A spec that asserted a warning's text was dropped. No mock or spy remains in
-  the specs the branch added; the log, history and executor are unit-specced through their own
-  interfaces.
-
-Every finding above has a spec, and each spec was run against the code as it was before its fix:
-it fails there and passes here. Two first drafts passed on the broken code as well, and were
-rewritten until they did not.
-
-@author Alex Goldring
-@copyright Company Named Limited (c) 2026