# `engine/network` — netcode package

Action-log replication, client-side prediction + reconciliation, and a
server-authoritative rollback orchestrator, layered over a pluggable transport.

## Layers (bottom → top)

| Layer | Pieces | Responsibility |
| --- | --- | --- |
| Transport | `transport/adapters/*` (`WebRTCDataChannel`, `WebTransport`, `WebSocket`, `NodeUDP`, `Simulated`, `Loopback`) | Move opaque byte buffers. UDP-style unless `reliable`/`ordered` say otherwise. |
| Channel | `transport/Channel.js` | Seq + ack-bitfield header; surfaces `onPacketAcked` / `onPacketLost` / `onPayload`. No retransmit. |
| Reliability / fragmentation | `transport/ReliableCommandPipeline.js`, `transport/fragments/*` | At-least-once commands; MTU fragmentation + NACK retransmit. |
| Sim core | `sim/*` (`ActionLog`, `SimAction`, `SimActionExecutor`, `RewindEngine`, `Snapshotter`, registries) | Record/apply/rewind replicated state mutations. |
| Replication | `replication/Replicator.js`, `replication/ScopeFilter.js` | Pack/unpack action records per peer, scope-filtered. |
| 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. |

## 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
when a mutation ledger is supplied.

## Opt-in primitives — NOT wired by `NetworkSession`

These are tested, public library surface intended for game code to wire up
directly; the facade does not use them. They are deliberate exports, not dead
code — fix bugs in them, don't delete them.

| Primitive | What it's for | To use it |
| --- | --- | --- |
| `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. |
| `diagnostics/SyncTest.js` | Determinism / desync checking | Compare state hashes across peers. |
| `adapters/Quaternion`/`Vector3InterpolationAdapter.js` | Interp building blocks | Reference when writing a component interpolation adapter (cf. `TransformInterpolationAdapter`). |

If you wire one of these into the facade, move its row up to the section above.
