@woosh/meep-engine 3.30.0 → 3.32.0

package/src/engine/network/README.md

@@ -15,14 +15,118 @@ server-authoritative rollback orchestrator, layered over a pluggable transport.
 | Orchestrator | `orchestrator/NetworkPeer.js`, `orchestrator/ServerAuthoritative{Server,Client}.js` | Per-tick send/recv, rollback (server), predict-reconcile (client). |
 | Facade | `NetworkSession.js` | One config + lifecycle surface; wires everything below. |
 
+## Smooth by default
+
+A game that wires a `NetworkSession` the obvious way renders smoothly at any display rate, with
+nothing else to set up. What that takes, and where it lives:
+
+- **One clock.** The `EntityManager`'s fixed step is the network tick. The session's
+  `NetworkSystem` opens a network frame as each step opens (`System.openFixedStep`) and closes it as
+  the step closes (`closeFixedStep`), so physics, controllers and game code all simulate inside the
+  frame. There is no `session.tick()` to call (it is deprecated and inert);
+  `entity_manager.update(dt)` — the engine loop — drives everything. Client time dilation is the
+  engine's `fixedStepTimeScale`: the step cadence stretches by a few percent, no step is dropped or
+  doubled. The session's timers — render playout, idle reaping, grace window — run on the same
+  frame time.
+- **The network writes where the simulation writes.** Every transport the session is given is held
+  (`DeferredTransport`): what arrives is applied as the next step opens, after the interpolation
+  system has put the simulation's truth back, never between a frame's blend and its draw, which is
+  where a browser usually delivers it.
+- **Every networked entity is interpolated, by role.** The session adds an `InterpolationSystem`
+  if the engine has none, and attaches an `Interpolated` to each networked entity (or adapts the
+  game's own): the local fixed-step timeline on the host and for entities a client owns; the
+  network's render-delayed playout for everything else on a client. Each replicated component
+  says how it is drawn and how a client corrects it — `replicate_interpolated(C, interpoland,
+  correction)`, for a C with `copy(other)`, or `replicate_discrete(C, correction)`;
+  `replicate_transform64(session)` (`network/adapters`) is the first for `Transform64`, with the
+  engine's full-precision pose interpoland and `POSE_CORRECTION`.
+- **The interpolation system owns interpolation** (`engine/interpolation`): it records every local
+  entity at the end of each step, blends every render frame ahead of pose readers such as the
+  camera, and before anything simulates, puts back the truth its blends displaced. An interpolated
+  entity is simulated at the fixed step; something that moves one between steps says so —
+  `Interpolated.snap` for a teleport (`PhysicsSystem.setPose` sets it), or
+  `InterpolationSystem.restore()` / `session.normalize_if_dirty()` before writing the truth. A write
+  over a blend without either is a write to a drawn pose, and the next step puts the truth back.
+- **The host publishes what changed.** Replicated components the host's simulation wrote directly
+  (physics, controllers) are published at the end of each step, recorded without being written
+  back — the host keeps full precision — and nothing an action already carried is sent twice.
+  `publish_changes: false` to publish by hand.
+- **Clients reconcile by comparison** (`reconcile: 'correct'`, the default): the host's state for
+  frame S is compared with what the client predicted for S, and a component that differs is
+  carried into the present by its `Correction` (`network/correction`) — the session knows no
+  component type. `POSE_CORRECTION` moves a `Transform64` by the offset, the turn in the body's
+  frame and the scale ratio, through physics for a body, and has the interpolation system draw it
+  as a glide, not a pop; `VELOCITY_CORRECTION` carries a rigid body's velocity difference;
+  `HOST_VALUE_CORRECTION` takes the host's value, for what a client does not predict. A client
+  predicts with each input exactly as the host will apply it, rounding included. `'replay'` keeps
+  the action-log rewind + replay, exact for simulations made only of deterministic actions.
+- **Late input is applied, not rolled back** (`late_input: 'apply'`, host default). Input
+  buffering (`simulation_delay_ticks`) and time dilation keep input on time; the client's per-tick
+  `FRAME_MARKER` keeps the dilation honest when it sends no input.
+
+Things the session cannot fix for the game:
+
+- A client must not simulate an entity it plays out from the network. Give a remote entity a
+  kinematic or static `RigidBody` on a client, or none: a dynamic one has local physics fighting
+  the network over its pose. The session does not check — it knows nothing of physics.
+- The host draws its own simulation. Client input that arrives later than the input buffer is
+  applied late and shows as a short hitch in the host's view of that client. Raise
+  `simulation_delay_ticks` on high-jitter links.
+- A client predicts the entities it owns. Anything else — a shared ball everybody pushes — is
+  played out from the host, a render delay behind. An entity that changes hands jumps between the
+  two timelines when it does.
+
+`NetworkSession.smoothness.spec.js` holds the line: a host and a client over a lossy, jittery link,
+drawn at 144 Hz on a 60 Hz step with packets landing between update and draw, every view of a moving
+entity measured frame by frame. The design and its history are in
+[`SMOOTHNESS_DESIGN.md`](./SMOOTHNESS_DESIGN.md).
+
+## Connecting, and coming back
+
+A client sends no input until its host has said which world the client is in. Each `connect()` —
+the first, and every reconnect — holds the client's action stream until the host answers the new
+connection:
+
+- **`RESUME_ACCEPT`**: the host kept the client's session, so the world the client has been
+  predicting on goes on. Everything predicted meanwhile is sent, input predicted while cut off
+  included, and the host applies it late.
+- **`INITIAL_SYNC`**: the host's snapshot replaces the client's world. Nothing predicted before it
+  is ever sent, on this connection or a later one that resumes it: that input was predicted on a
+  world that is gone. The client's input starts at the frame the snapshot sets its counter to.
+
+The first answer is the answer. The host sends each `INITIAL_SYNC` more than once, against loss,
+and a host that has finished with a client's old session readmits its new connection as a fresh
+peer before it reads the `RESUME_HELLO` on it — so a `RESUME_REJECT` can arrive after the snapshot it
+announces. A client acts on neither once the connection has its answer: the copies would put what it
+owns back behind input it has already sent, and the reject would throw away the token the snapshot
+issued.
+
+The host keeps to the same rule from its side, because what a peer can make it do has to be bounded
+by what the host decided, not by how often the peer asks. It answers a connection's `RESUME_HELLO`
+once and ignores any later one on that connection, and it sends a connection its `INITIAL_SYNC` —
+the copies against loss included — once, when it takes the connection for a fresh peer: as it binds
+it, or after refusing the connection's claim to resume. Each is the whole world, serialized; no
+number of claims buys another. A connection here is a transport the host binds with `connect()`, so
+a reconnect has to reach the host as a new one — the fresh transport a `transport_factory` returns,
+bound once the host has seen the old one end. One that lands on a connection the host still holds
+is a second claim on that connection, and is not sent the world again.
+
+A chunk of a fragmented message that goes missing — of an `INITIAL_SYNC`, typically — is re-sent when
+the receiver asks with a `NACK_FRAGMENT`, and that repair is bounded the same way. A NACK re-sends
+each chunk of the message at most once however many times it names it, and nothing for an index the
+message does not have; the host answers three NACKs per message. So repair adds at most three copies
+of any message the host chose to send.
+
 ## Wired automatically by `NetworkSession`
 
 `NetworkPeer` (and through it `Channel`, `Replicator`, `ActionLog`,
 `SimActionExecutor`, the registries, `ReplicationSlotTable`, `Baseline`,
 the fragment layer, and `ReliableCommandPipeline`), the two orchestrators
 (and through them `RewindEngine` and `InputRing`), plus `TimeDilation`,
-`AdaptiveRenderDelay`, `InterpolationLog`, `NetworkSystem`, `NetworkIdentity`,
-and `Snapshotter`. `ChangedEntitySet` / `MutationLedger` are wired on the host
+`AdaptiveRenderDelay`, `RenderPlayout`, `InterpolationLog`, `NetworkSystem`,
+`NetworkIdentity`, `Snapshotter`, `SmoothingState` (through the
+`InterpolationSystem`) and `PredictionHistory`, and the engine's
+`InterpolationSystem` itself. `ChangedEntitySet` / `MutationLedger` are wired on the host
 when a mutation ledger is supplied.
 
 ## Opt-in primitives — NOT wired by `NetworkSession`
@@ -35,7 +139,6 @@ code — fix bugs in them, don't delete them.
 | --- | --- | --- |
 | `time/TimeSync.js` | NTP-style clock-offset estimation | Drive it from a ping/pong round-trip; read `offset()` / `best_rtt()`. |
 | `time/JitterBuffer.js` | Frame-tagged reorder/hold buffer | `push(frame, payload)`; `drain_until(current_frame, cb)`. |
-| `sim/SmoothingState.js` | Hide the post-reconcile correction snap | After reconcile, feed the pre/post pose; add the decaying error in your render path. |
 | `state/PriorityAccumulator.js` | Bandwidth-aware action scheduling | Consult `sorted_descending()` when an outgoing packet approaches MTU. |
 | `diagnostics/BandwidthMeter.js` | Throughput accounting | Sample around `transport.getStats()`. |
 | `diagnostics/ReplayLog.js` | Record/replay packet streams | Capture inbound/outbound for offline repro. |

package/src/engine/network/SMOOTHNESS_DESIGN.md

@@ -0,0 +1,392 @@
+# 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.
+
+**The host publishes what changed.** 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, against a baseline of what the
+  peers hold that every executed action also updates; `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, 252]`; 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

package/src/engine/network/adapters/PoseCorrection.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Corrects a {@link Transform64} the way the simulation would have carried the difference:
+ *
+ *  - position by the offset;
+ *  - orientation by the turn `e` that takes the predicted orientation to the host's in the body's
+ *    own frame (`predicted · e = host`), applied on the same side to every later state — whatever
+ *    world-frame rotation the body made since, it makes from the corrected orientation too
+ *    (`q_now · e`);
+ *  - scale by the ratio.
+ *
+ * Two poses are the same when they are within what the wire cannot tell apart (see the tolerances
+ * above).
+ *
+ * The live pose of a rigid body is moved through its physics system, so a sleeping body wakes and
+ * its broadphase leaves follow; and the step is hidden in what is drawn — the interpolation system
+ * shifts the entity's recent records by the correction and draws the opposite offset, fading.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PoseCorrection extends Correction {
+    /**
+     * @param {Transform64} server
+     * @param {Transform64} predicted
+     * @returns {boolean}
+     */
+    same(server: Transform64, predicted: Transform64): boolean;
+    /**
+     * @param {Transform64} state
+     * @param {Transform64} server
+     * @param {Transform64} predicted
+     */
+    carry(state: Transform64, server: Transform64, predicted: Transform64): void;
+    /**
+     * @param {CorrectionTarget} target
+     * @param {Transform64} server
+     * @param {Transform64} predicted
+     * @returns {number} how far the position moved, in world units
+     */
+    apply(target: CorrectionTarget, server: Transform64, predicted: Transform64): number;
+    #private;
+}
+/**
+ * The shared {@link PoseCorrection}, for {@link Transform64}.
+ * @type {PoseCorrection}
+ */
+export const POSE_CORRECTION: PoseCorrection;
+import { Correction } from "../correction/Correction.js";
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+//# sourceMappingURL=PoseCorrection.d.ts.map

package/src/engine/network/adapters/PoseCorrection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PoseCorrection.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/adapters/PoseCorrection.js"],"names":[],"mappings":"AAuDA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAUI;;;;OAIG;IACH,aAJW,WAAW,aACX,WAAW,GACT,OAAO,CAyBnB;IAED;;;;OAIG;IACH,aAJW,WAAW,UACX,WAAW,aACX,WAAW,QASrB;IAED;;;;;OAKG;IACH,wCAJW,WAAW,aACX,WAAW,GACT,MAAM,CAoClB;;CAmCJ;AAED;;;GAGG;AACH,8BAFU,cAAc,CAE4B;2BA/MzB,6BAA6B;4BAH5B,oCAAoC"}