@woosh/meep-engine 2.169.4 → 2.170.0

package/src/engine/network/NetworkSession.js

@@ -1,2036 +1,2037 @@
-import { assert } from "../../core/assert.js";
-import { BinaryBuffer } from "../../core/binary/BinaryBuffer.js";
-import Signal from "../../core/events/signal/Signal.js";
-import { EntityObserver } from "../ecs/EntityObserver.js";
-import { UUID } from "../ecs/guid/UUID.js";
-import { BinarySerializationRegistry, } from "../ecs/storage/binary/BinarySerializationRegistry.js";
-
-import { NetworkIdentity } from "./ecs/components/NetworkIdentity.js";
-import { make_owner_authorization } from "./ecs/owner_authorization.js";
-import { NetworkSystem } from "./ecs/NetworkSystem.js";
-import { NetworkIdentitySerializationAdapter, } from "./ecs/serialization/NetworkIdentitySerializationAdapter.js";
-import { NetworkPeer, ResumeRejectReason, } from "./orchestrator/NetworkPeer.js";
-import { ServerAuthoritativeClient } from "./orchestrator/ServerAuthoritativeClient.js";
-import { ServerAuthoritativeServer } from "./orchestrator/ServerAuthoritativeServer.js";
-import { OwnerAwareScope } from "./replication/ScopeFilter.js";
-import { BinaryInterpolationAdapter, InterpolationKind, } from "../interpolation/BinaryInterpolationAdapter.js";
-import { InterpolationLog } from "../interpolation/InterpolationLog.js";
-import { SimAction } from "./sim/SimAction.js";
-import { snapshotter_emit } from "./sim/Snapshotter.js";
-import { AdaptiveRenderDelay } from "./time/AdaptiveRenderDelay.js";
-import { TimeDilation } from "./time/TimeDilation.js";
-
-/**
- * Roles a session can occupy. The orchestrator it wires up underneath is
- * uniquely determined by the role.
- *
- *   - `'client'`  → {@link ServerAuthoritativeClient}: predicts locally
- *                   when an input sampler is registered; reconciles to
- *                   server-authoritative state arriving via AUTH_STATE.
- *                   With no input sampler, a client is a pure spectator
- *                   — it receives the action stream, smooths via
- *                   interpolation, and never predicts or rewinds. This
- *                   is the default role and covers both "playing" and
- *                   "spectating" use cases.
- *   - `'host'`    → {@link ServerAuthoritativeServer}: simulation
- *                   authority for one or more clients; runs the optional
- *                   server-side input buffer (`simulation_delay_ticks`).
- *
- * @readonly @enum {string}
- */
-export const NetworkSessionRole = Object.freeze({
-    Client: 'client',
-    Host: 'host',
-});
-
-const DEFAULT_TICK_RATE_HZ = 60;
-const DEFAULT_SIMULATION_DELAY_TICKS = 4;
-const DEFAULT_INITIAL_RENDER_DELAY_FRAMES = 6;
-
-/**
- * Default depth of the action-log ring (in frames). This single value bounds
- * THREE distinct horizons at once:
- *   1. Rollback depth — how far back the server can rewind+replay to fold in
- *      late client input.
- *   2. Fresh-connect back-fill range — how many past frames a newly-connected
- *      peer's action stream covers before it has acked anything.
- *   3. Action-stream retransmit window — how long an unacked frame stays
- *      resendable before it ages out of the ring.
- *
- * At 60 Hz, 32 frames ≈ 0.53 s. That is comfortable for rollback but tight for
- * loss recovery on high-latency links: if a peer's ack RTT + jitter exceeds the
- * window, unacked frames age out and the action stream develops gaps that fall
- * back to the heavier RECOVERY_REQUEST → STATE_BURST path. Raise `frame_capacity`
- * for high-RTT / lossy deployments (memory cost is ~one buffer per frame per
- * orchestrator, so it is cheap to grow).
- */
-const DEFAULT_ACTION_LOG_FRAME_CAPACITY = 32;
-const PULL_PER_MS = 0.0005;        // wall-clock low-pass on render frame state machine
-const MAX_CLIENT_DILATED_TICKS_PER_STEP = 3;
-const MAX_FIXED_STEPS_PER_TICK = 8;
-
-const DEFAULT_SERVER_RESUME_GRACE_MS = 30_000;
-
-// Inbound-silence budget before a peer is reaped (host → grace, client →
-// reconnect ladder). Matches GNS's TimeoutConnected default. The facade pumps
-// at least one packet per tick in each direction (host: AUTH_STATE +
-// TIME_DILATION; client: action-stream / empty-ack), so a live, mutually-
-// ticking pair never approaches this — only a genuinely-gone peer does. Set 0
-// to disable (e.g. turn-based games, or transports that signal disconnect
-// themselves). Primarily for connectionless transports (NodeUDP, WebRTC /
-// WebTransport datagram), where no close event ever fires.
-const DEFAULT_CONNECTION_TIMEOUT_MS = 10_000;
-
-const DEFAULT_RECONNECT_POLICY = Object.freeze({
-    enabled: true,
-    max_attempts: 8,
-    base_delay_ms: 200,
-    max_delay_ms: 5_000,
-    exponential_factor: 2.0,
-    total_timeout_ms: 60_000,
-    accept_state_resync: true,
-});
-
-/**
- * Client-side reconnect state machine values.
- * @readonly @enum {string}
- */
-const ReconnectState = Object.freeze({
-    Connected: 'connected',
-    Reconnecting: 'reconnecting',
-    Resyncing: 'resyncing',
-    Lost: 'lost',
-});
-
-/**
- * Scratch buffer size used for AUTH_STATE assembly and net_mutate_component
- * event payloads. Sized for the common cases (Transform ≈ 36 B); components
- * with richer payloads need this raised or a different scratch lifecycle.
- */
-const SCRATCH_BUFFER_BYTES = 1024;
-
-/**
- * Shared zero-length payload for empty ack packets. Hoisted to module scope so
- * the per-peer, per-tick ack send doesn't allocate a fresh array each time.
- * @type {Uint8Array}
- */
-const EMPTY_PAYLOAD = new Uint8Array(0);
-
-/**
- * High-level networking facade. Wraps the orchestrator + state machinery
- * into one config + lifecycle surface. The lower-level orchestrators
- * remain reachable through `session.server` / `session.client` /
- * `session.peer` for callers that need to override defaults post-hoc.
- *
- * Replication is component-driven: attaching a {@link NetworkIdentity}
- * to an entity registers it with the session via an `EntityObserver`.
- * Mutation is event-driven: callers fire
- * `dataset.sendEvent(entity, "net_mutate_component", payload)`.
- *
- * Per-tick driving is a single `session.tick(dt_seconds)`. The session
- * runs fixed-timestep stepping, client time dilation, server-side input
- * buffer, AUTH_STATE dispatch, time-dilation feedback, and interpolated
- * rendering for remote-owned entities.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class NetworkSession {
-
-    // ---- Pre-start registration (set via replicate / defineAction / defineInputSampler) ----
-
-    /**
-     * User-registered replicated component classes, in `replicate()` call
-     * order. Finalized at `start()` into {@link #replicated} with
-     * `NetworkIdentity` prepended.
-     * @private @type {Array<{klass: Function, interp: BinaryInterpolationAdapter|null}>}
-     */
-    #user_replicated = [];
-
-    /**
-     * Finalized at `start()`. Insertion order = wire-format order;
-     * `NetworkIdentity` is the first entry (its slot allocation must
-     * fire before subsequent components attach during initial-sync apply).
-     * Each value: `{ interp, interp_type_id }`.
-     * @private @type {Map<Function, {interp: BinaryInterpolationAdapter|null, interp_type_id: number}>}
-     */
-    #replicated = new Map();
-
-    /**
-     * Type_id → ComponentClass for the synthetic ReplaceComponentAction.
-     * @private @type {Function[]}
-     */
-    #interp_type_id_to_class = [];
-
-    /** @private @type {Array<Function>} */
-    #user_action_classes = [];
-
-    /** @private @type {((frame: number) => Array<SimAction>|null) | null} */
-    #input_sampler = null;
-
-    // ---- Set in start() ----
-
-    /** @private @type {ServerAuthoritativeServer|null} */
-    #server = null;
-    /** @private @type {ServerAuthoritativeClient|null} */
-    #client = null;
-    /** @private @type {NetworkPeer|null} */
-    #peer = null;
-    /** @private @type {EntityObserver|null} */
-    #identity_observer = null;
-    /** @private @type {InterpolationLog|null} */
-    #interp_log = null;
-    /** @private @type {Function|null} */
-    #ReplaceComponentAction = null;
-
-    // ---- Per-entity tracking ----
-
-    /**
-     * `entity_id → "net_mutate_component" listener` so detach can clean up.
-     * Also doubles as the iterable of all networked entities.
-     * @private @type {Map<number, Function>}
-     */
-    #event_listeners = new Map();
-
-    /**
-     * Entities the local peer does NOT own — driven by the render
-     * interpolation pass.
-     * @private @type {Set<number>}
-     */
-    #remote_entities = new Set();
-
-    // ---- Render-frame interpolation state ----
-
-    /** @private @type {number} */ #latest_received_frame = -1;
-    /** @private @type {number} */ #smooth_render_frame = -1;
-    /** @private @type {number} */ #smooth_last_wall_ms = -1;
-
-    /**
-     * Set after `#render_interpolated_entities` writes interp values into
-     * live components; cleared by `normalize_if_dirty`. Drives the
-     * canonical-form invariant: live is canonical when this is false,
-     * polluted (smooth) when true.
-     * @private @type {boolean}
-     */
-    render_dirty = false;
-
-    // ---- Per-tick driver state ----
-
-    /** @private @type {number} */ #local_frame = 0;
-    /** @private @type {number} */ #local_frame_accum = 0;
-    /** @private @type {number} */ #sim_accum_ms = 0;
-
-    /** @private @type {Set<number>} */
-    #connected_peers = new Set();
-
-    /**
-     * Host-only: peer_id → remaining-resends. Drained in
-     * `#on_host_tick_complete` once `current_sim_frame >= 0`. Sent twice
-     * for loss tolerance; production code should re-send on receiver
-     * RECOVERY request.
-     * @private @type {Map<number, number>}
-     */
-    #pending_initial_sync = new Map();
-
-    /**
-     * Sampled-action ledger for predict-reconcile replay. The sampler
-     * reads live input, so re-calling it during reconcile would give
-     * wrong results; replay reads from here instead.
-     * @private @type {Map<number, Array<{type_id: number, bytes: Uint8Array}>>}
-     */
-    #sampled_actions_per_frame = new Map();
-
-    /** @private @type {boolean} */
-    #started = false;
-
-    // ---- Host-side: per-peer session token + grace state ----
-
-    /**
-     * Tokens issued at first INITIAL_SYNC, kept while the peer is
-     * connected or in the grace window. Used to authenticate
-     * RESUME_HELLO.
-     * @private @type {Map<number, UUID>}
-     */
-    #peer_session_tokens = new Map();
-
-    /**
-     * Peers currently in the post-disconnect grace window. Value carries
-     * the deadline (wall-clock ms) and the cached `last_acked_frame` so
-     * a successful resume restores the action-stream baseline.
-     * @private @type {Map<number, { deadline_ms: number, last_acked: number }>}
-     */
-    #peer_grace_state = new Map();
-
-    /**
-     * Per-peer transport onDisconnect listener bookkeeping so we can
-     * unsubscribe when the peer is fully dropped.
-     * @private @type {Map<number, { transport: object, listener: Function }>}
-     */
-    #peer_transport_listeners = new Map();
-
-    // ---- Client-side: session token + reconnect state machine ----
-
-    /**
-     * Server-issued session token (raw UUID v1 bytes). Set on first
-     * INITIAL_SYNC arrival; refreshed on every Tier-3 resync. Sent in
-     * `RESUME_HELLO` to claim continuity with a prior session record.
-     * Observable to game code for diagnostics; not auth-grade.
-     * @type {UUID|null}
-     */
-    session_token = null;
-
-    /** @private @type {string} */
-    #reconnect_state = ReconnectState.Connected;
-    /** @private @type {number} */
-    #reconnect_attempt = 0;
-    /** @private @type {number} */
-    #reconnect_elapsed_ms = 0;
-    /** @private @type {number} */
-    #reconnect_next_delay_ms = 0;
-    /** @private @type {number} */
-    #reconnect_timer_remaining_ms = 0;
-    /** @private @type {object|null} */
-    #current_transport = null;
-    /** @private @type {Function|null} */
-    #current_transport_listener = null;
-    /** @private @type {number} */
-    #remote_peer_id = -1;
-
-    // ---- Signals (initialized inline because they take no input) ----
-
-    /**
-     * Host: a connected peer's transport reported a disconnect (the peer
-     * has entered the grace window). Args: `(peer_id, reason)`.
-     * @type {Signal}
-     */
-    onPeerLost = new Signal();
-
-    /**
-     * Host: a peer has been permanently freed — either via
-     * `drop_peer()`, a grace-window timeout, or a peer-initiated
-     * DISCONNECT. Args: `(peer_id, reason)`.
-     * @type {Signal}
-     */
-    onPeerPermanentlyDropped = new Signal();
-
-    /**
-     * Client: the transport has reported a disconnect, and the
-     * reconnect ladder has started. Args: `(reason)`.
-     * @type {Signal}
-     */
-    onConnectionLost = new Signal();
-
-    /**
-     * Client: about to rebuild the transport and dial the host. Args:
-     * `(attempt_number)`.
-     * @type {Signal}
-     */
-    onReconnectAttempt = new Signal();
-
-    /**
-     * Client: reconnect succeeded. Args: `({ state_resynced: boolean })` —
-     * `state_resynced` is `true` if we fell through to Tier-3 (server
-     * had purged our state and re-sent INITIAL_SYNC), `false` for the
-     * happy Tier-2 path where the action stream just resumed.
-     * @type {Signal}
-     */
-    onReconnected = new Signal();
-
-    /**
-     * Client: the reconnect ladder is exhausted, or the host explicitly
-     * kicked us with a DISCONNECT packet, or `reconnect.enabled` is
-     * false and the link dropped. Args: `(reason)`.
-     * @type {Signal}
-     */
-    onConnectionPermanentlyLost = new Signal();
-
-    // ---- Set in constructor (depend on input or imperative setup) ----
-
-    /** @private */ #transport = null;
-    /** @private */ #scope_filter = null;
-    /** @private @type {TimeDilation} */ #time_dilation;
-    /** @private @type {AdaptiveRenderDelay} */ #adaptive_render_delay;
-    /** @private @type {BinaryBuffer} */ #scratch_send_buf;
-    /** @private @type {BinaryBuffer} */ #scratch_interp_buf;
-    /** @private @type {() => void} */ #bound_normalize_if_dirty;
-
-    /** @private @type {number} */ #server_resume_grace_ms;
-    /** @private @type {object} */ #reconnect_policy;
-    /** @private @type {(() => object) | null} */ #transport_factory;
-
-    /** @private @type {number} ms of inbound silence before reaping; 0 = off */ #connection_timeout_ms;
-    /** @private @type {number} monotonic ms clock advanced by tick(dt) */ #liveness_clock_ms = 0;
-    /**
-     * Per-peer liveness mark: the inbound-packet count last seen and the clock
-     * time it was last seen advancing. Drives idle reaping.
-     * @private @type {Map<number, { count: number, since_ms: number }>}
-     */
-    #peer_inbound_mark = new Map();
-
-    /**
-     * @param {{
-     *   entity_manager: EntityManager,
-     *   transport?: object,
-     *   transport_factory?: (() => object),
-     *   role?: 'client'|'host',
-     *   local_peer_id?: number,
-     *   simulation_delay_ticks?: number,
-     *   tick_rate_hz?: number,
-     *   binary_registry?: BinarySerializationRegistry,
-     *   scope_filter?: object,
-     *   time_dilation?: TimeDilation,
-     *   adaptive_render_delay?: AdaptiveRenderDelay,
-     *   server_resume_grace_ms?: number,
-     *   connection_timeout_ms?: number,
-     *   reconnect?: {
-     *     enabled?: boolean,
-     *     max_attempts?: number,
-     *     base_delay_ms?: number,
-     *     max_delay_ms?: number,
-     *     exponential_factor?: number,
-     *     total_timeout_ms?: number,
-     *     accept_state_resync?: boolean,
-     *   },
-     * }} options
-     *
-     * - `transport` is not connected at construction — call {@link connect}
-     *   with an explicit remote peer id after {@link start}.
-     * - `transport_factory` (client role): zero-arg function that returns
-     *   a fresh `Transport` on each reconnect attempt. Required for
-     *   automatic reconnect; without it, transport-level disconnects fall
-     *   straight through to `onConnectionPermanentlyLost`.
-     * - `role` defaults to `'client'`. See {@link NetworkSessionRole}.
-     * - `local_peer_id` defaults to 0 for host, 1 for client. Must be
-     *   unique across peers.
-     * - `simulation_delay_ticks` is honored only under `role: 'host'`.
-     *   Default 4. See {@link ServerAuthoritativeServer}.
-     * - `tick_rate_hz` defaults to 60.
-     * - `frame_capacity` sizes the action-log ring (rollback depth + back-fill
-     *   range + retransmit window — see {@link DEFAULT_ACTION_LOG_FRAME_CAPACITY}).
-     *   Default 32. Raise it for high-RTT / lossy links.
-     * - `scope_filter` defaults to {@link OwnerAwareScope} on the host.
-     * - `server_resume_grace_ms` (host role): how long peer state is
-     *   retained after a transport drop before being freed. Default 30s.
-     * - `connection_timeout_ms`: inbound-silence budget before a peer is
-     *   reaped (host → grace, client → reconnect ladder). Default 10s; set 0
-     *   to disable. Mainly for connectionless transports, which never emit a
-     *   disconnect event — see {@link DEFAULT_CONNECTION_TIMEOUT_MS}.
-     * - `reconnect` (client role): policy for the reconnect ladder. See
-     *   {@link DEFAULT_RECONNECT_POLICY}. Set `enabled: false` to opt
-     *   out entirely.
-     */
-    constructor({
-                    entity_manager,
-                    transport = null,
-                    transport_factory = null,
-                    role = NetworkSessionRole.Client,
-                    local_peer_id = -1,
-                    simulation_delay_ticks = DEFAULT_SIMULATION_DELAY_TICKS,
-                    tick_rate_hz = DEFAULT_TICK_RATE_HZ,
-                    frame_capacity = DEFAULT_ACTION_LOG_FRAME_CAPACITY,
-                    binary_registry = null,
-                    scope_filter = null,
-                    time_dilation = null,
-                    adaptive_render_delay = null,
-                    server_resume_grace_ms = DEFAULT_SERVER_RESUME_GRACE_MS,
-                    connection_timeout_ms = DEFAULT_CONNECTION_TIMEOUT_MS,
-                    reconnect = null,
-                } = {}) {
-        assert.ok(entity_manager !== undefined && entity_manager !== null,
-            'NetworkSession: entity_manager is required');
-        if (role !== NetworkSessionRole.Client && role !== NetworkSessionRole.Host) {
-            throw new Error(`NetworkSession: invalid role '${role}'`);
-        }
-        assert.isNumber(tick_rate_hz, 'tick_rate_hz');
-        assert.ok(tick_rate_hz > 0, 'tick_rate_hz must be positive');
-        assert.isNonNegativeInteger(simulation_delay_ticks, 'simulation_delay_ticks');
-        assert.isPositiveInteger(frame_capacity, 'frame_capacity');
-
-        /**
-         * @readonly
-         * @type {EntityManager}
-         */
-        this.entity_manager = entity_manager;
-
-        /**
-         * @readonly
-         * @type {EntityComponentDataset}
-         */
-        this.world = entity_manager.dataset;
-
-        /**
-         * @readonly
-         * @type {NetworkSessionRole|string}
-         */
-        this.role = role;
-
-        /**
-         * @readonly
-         * @type {number}
-         */
-        this.tick_period_ms = 1000 / tick_rate_hz;
-
-        /**
-         * @readonly
-         * @type {number}
-         */
-        this.simulation_delay_ticks = role === NetworkSessionRole.Host
-            ? simulation_delay_ticks
-            : 0;
-
-        /**
-         * Depth of the action-log ring passed to the orchestrator. Bounds
-         * rollback depth, back-fill range, and retransmit window — see
-         * {@link DEFAULT_ACTION_LOG_FRAME_CAPACITY}.
-         * @readonly
-         * @type {number}
-         */
-        this.frame_capacity = frame_capacity;
-
-        /**
-         * @readonly
-         * @type {number}
-         */
-        this.local_peer_id = local_peer_id >= 0
-            ? local_peer_id
-            : (role === NetworkSessionRole.Host ? 0 : 1);
-
-        /**
-         * @readonly
-         * @type {BinarySerializationRegistry}
-         */
-        this.binary_registry = binary_registry || new BinarySerializationRegistry();
-
-        this.#transport = transport;
-        this.#scope_filter = scope_filter;
-
-        this.#time_dilation = time_dilation || new TimeDilation({
-            target_buffer_depth: this.simulation_delay_ticks > 0 ? this.simulation_delay_ticks : 2,
-            max_dilation: 0.05,
-            gain: 0.05,
-        });
-        this.#adaptive_render_delay = adaptive_render_delay || new AdaptiveRenderDelay({
-            tick_period_ms: this.tick_period_ms,
-            min_delay_frames: 2,
-            max_delay_frames: 30,
-            initial_delay_frames: DEFAULT_INITIAL_RENDER_DELAY_FRAMES,
-            history_size: 60,
-            safety_multiplier: 2.0,
-            decay_per_sample_ms: 1.0,
-        });
-
-        this.#scratch_send_buf = new BinaryBuffer();
-        this.#scratch_send_buf.setCapacity(SCRATCH_BUFFER_BYTES);
-
-        this.#scratch_interp_buf = new BinaryBuffer();
-        this.#scratch_interp_buf.setCapacity(SCRATCH_BUFFER_BYTES);
-
-        /**
-         * @type {() => void}
-         */
-        this.#bound_normalize_if_dirty = () => this.normalize_if_dirty();
-
-        this.#server_resume_grace_ms = server_resume_grace_ms;
-        assert.isNonNegativeInteger(connection_timeout_ms, 'connection_timeout_ms');
-        this.#connection_timeout_ms = connection_timeout_ms;
-        this.#reconnect_policy = Object.freeze({ ...DEFAULT_RECONNECT_POLICY, ...(reconnect || {}) });
-        this.#transport_factory = transport_factory;
-    }
-
-    // ----------------------------------------------------------------
-    //  Configuration (must run before start())
-    // ----------------------------------------------------------------
-
-    /**
-     * Register a component class for network replication.
-     *
-     * The component must have a {@link BinaryClassSerializationAdapter}
-     * registered for its `typeName` in the session's `binary_registry`
-     * before {@link start} is called — that adapter handles the wire
-     * format and rewind capture.
-     *
-     * `interpolator` is optional. When omitted, the component's state
-     * snaps on each received update (no sub-tick smoothing). When
-     * provided, it must extend {@link BinaryInterpolationAdapter} with
-     * `kind = InterpolationKind.Linear` — Discrete and Cubic are
-     * reserved for future support and currently throw.
-     *
-     * The order of `replicate()` calls must match across all peers in
-     * the session: AUTH_STATE payload layout iterates components in
-     * insertion order.
-     *
-     * @param {Function} ComponentClass
-     * @param {BinaryInterpolationAdapter} [interpolator]
-     */
-    replicate(ComponentClass, interpolator = null) {
-        this.#assert_not_started('replicate');
-        assert.isFunction(ComponentClass, 'ComponentClass');
-
-        if (ComponentClass === NetworkIdentity) {
-            throw new Error("NetworkSession.replicate: NetworkIdentity is auto-replicated; do not call replicate() for it");
-        }
-
-        for (const entry of this.#user_replicated) {
-            if (entry.klass === ComponentClass) {
-                throw new Error(`NetworkSession.replicate: ${ComponentClass.typeName ?? ComponentClass.name} already registered`);
-            }
-        }
-        if (interpolator !== null) {
-            if (!(interpolator instanceof BinaryInterpolationAdapter)) {
-                throw new Error("NetworkSession.replicate: interpolator must extend BinaryInterpolationAdapter");
-            }
-            if (interpolator.kind !== InterpolationKind.Linear) {
-                throw new Error(
-                    `NetworkSession.replicate: only Linear interpolation is currently supported; ` +
-                    `got kind=${interpolator.kind} for ${ComponentClass.typeName ?? ComponentClass.name}. ` +
-                    `Omit the interpolator argument for snap (Discrete) behavior; Cubic is reserved.`,
-                );
-            }
-        }
-        this.#user_replicated.push({ klass: ComponentClass, interp: interpolator });
-    }
-
-    /**
-     * Register a user-defined {@link SimAction} subclass with the
-     * session. The action's `type_id` is assigned by the underlying
-     * registry when {@link start} runs. Calling code constructs
-     * instances directly (`new MyAction(...)`) and dispatches via
-     * {@link send} or returns them from the input sampler.
-     *
-     * @param {Function} SimActionClass class extending SimAction
-     */
-    defineAction(SimActionClass) {
-        this.#assert_not_started('defineAction');
-        assert.isFunction(SimActionClass, 'SimActionClass');
-        this.#user_action_classes.push(SimActionClass);
-    }
-
-    /**
-     * Install a per-tick input sampler (client role only). The sampler
-     * is called once per local sim tick at predict time and must return
-     * an array of {@link SimAction} instances representing the local
-     * peer's inputs for that frame. The session executes them locally
-     * (predict), records their serialized bytes for replay, and forwards
-     * them over the action stream.
-     *
-     * The sampler is NOT called during reconciliation replay — the
-     * recorded bytes are deserialized and re-executed instead, so the
-     * action set faithfully reproduces what the user originally
-     * sampled at that frame.
-     *
-     * Return `[]` (or `null`) for ticks with no inputs.
-     *
-     * @param {(frame: number) => Array<SimAction>|null} sampler_fn
-     */
-    defineInputSampler(sampler_fn) {
-        this.#assert_not_started('defineInputSampler');
-        assert.isFunction(sampler_fn, 'sampler_fn');
-
-        if (this.role !== NetworkSessionRole.Client) {
-            throw new Error(`NetworkSession.defineInputSampler: only valid for role='${NetworkSessionRole.Client}', got '${this.role}'`);
-        }
-
-        this.#input_sampler = sampler_fn;
-    }
-
-    // ----------------------------------------------------------------
-    //  Lifecycle
-    // ----------------------------------------------------------------
-
-    /**
-     * Wire the session to the engine. After this, the EntityObserver
-     * is active, the right orchestrator is constructed, and a
-     * {@link NetworkSystem} is attached. Subsequent {@link replicate}
-     * / {@link defineAction} / {@link defineInputSampler} calls throw.
-     *
-     * Pre-condition: every component class passed to {@link replicate}
-     * must already have a `BinaryClassSerializationAdapter` registered
-     * in the session's binary_registry.
-     */
-    async start() {
-        if (this.#started) throw new Error("NetworkSession.start: already started");
-
-        // Auto-register the NetworkIdentity adapter so initial-sync can
-        // ship it across the wire. Allow caller-supplied registrations
-        // to win (game might have a custom one).
-        if (this.binary_registry.getAdapter(NetworkIdentity.typeName) === undefined) {
-            this.binary_registry.registerAdapter(new NetworkIdentitySerializationAdapter(), NetworkIdentity.typeName);
-        }
-
-        // Finalize the replicated-components ordering: NetworkIdentity
-        // FIRST (so it gets type_id=0 and arrives as the first per-entity
-        // record in snapshots — receiver attaches NetworkIdentity first,
-        // which triggers slot-table allocation before any other component
-        // payload needs to look up `entity_for(network_id)`).
-        let next_id = 0;
-        const network_identity_scratch = new BinaryBuffer();
-        network_identity_scratch.setCapacity(SCRATCH_BUFFER_BYTES);
-        this.#replicated.set(NetworkIdentity, {
-            interp: null,
-            interp_type_id: next_id++,
-        });
-        this.#interp_type_id_to_class[0] = NetworkIdentity;
-        for (const { klass, interp } of this.#user_replicated) {
-            const interp_type_id = next_id++;
-            this.#replicated.set(klass, { interp, interp_type_id });
-            this.#interp_type_id_to_class[interp_type_id] = klass;
-        }
-
-        // Verify each replicated component has a serialization adapter.
-        for (const ComponentClass of this.#replicated.keys()) {
-            const name = ComponentClass.typeName;
-            if (typeof name !== 'string') {
-                throw new Error(`NetworkSession.start: ${ComponentClass.name} has no static .typeName; cannot look up its adapter`);
-            }
-            if (this.binary_registry.getAdapter(name) === undefined) {
-                throw new Error(`NetworkSession.start: no BinaryClassSerializationAdapter registered for ${name}; register one in the binary_registry before calling start()`);
-            }
-        }
-
-        // Build the synthetic ReplaceComponentAction now so it's in the
-        // action_classes list when the orchestrator is constructed.
-        this.#ReplaceComponentAction = this.#make_replace_component_action_class();
-
-        const replicated_components = Array.from(this.#replicated.keys());
-        const action_classes = [...this.#user_action_classes, this.#ReplaceComponentAction];
-
-        const orchestrator_opts = {
-            world: this.world,
-            binary_registry: this.binary_registry,
-            replicated_components,
-            action_classes,
-            frame_capacity: this.frame_capacity,
-        };
-
-        if (this.role === NetworkSessionRole.Host) {
-            this.#server = new ServerAuthoritativeServer({
-                ...orchestrator_opts,
-                simulation_delay_ticks: this.simulation_delay_ticks,
-            });
-            this.#peer = this.#server.peer;
-            this.#peer.replicator.scope_filter = this.#scope_filter || new OwnerAwareScope({
-                world: this.world,
-                slot_table: this.#server.slot_table,
-                identity_class: NetworkIdentity,
-            });
-            this.#server.onTickComplete.add((sim_frame) => this.#on_host_tick_complete(sim_frame));
-        } else {
-            // Client role: covers both "playing" (input sampler registered)
-            // and "spectator" (no sampler — sampler-driven onPredict
-            // returns no actions, so the predict-reconcile machinery
-            // exists but stays idle).
-            this.#client = new ServerAuthoritativeClient({
-                ...orchestrator_opts,
-                time_dilation: this.#time_dilation,
-            });
-            this.#peer = this.#client.peer;
-            if (this.#scope_filter) {
-                this.#peer.replicator.scope_filter = this.#scope_filter;
-            }
-            this.#wire_client_predict_reconcile();
-        }
-
-        // Install the canonical-form normalize hook on the executor.
-        // Anything that calls executor.execute — predict apply, action-
-        // stream apply, reconcile replay — first normalizes the world.
-        // Idempotent: cheap when `render_dirty` is false (one bool
-        // check), expensive (one adapter.deserialize per remote-owned
-        // component) only on the first execute after a render pass.
-        this.#peer.executor.before_execute = this.#bound_normalize_if_dirty;
-
-        // Secure-by-default inbound authorization on the host: a remote client
-        // may only mutate entities it owns (NetworkIdentity.owner_peer_id ===
-        // sender); the authoritative server (sender === local_peer_id) may
-        // mutate anything. Without this a connected peer can craft an action
-        // targeting another peer's (or a server-owned) entity. Games needing a
-        // different policy can overwrite executor.authorize after start().
-        // Client sessions trust the server's stream and so are not gated.
-        if (this.role === NetworkSessionRole.Host) {
-            this.#peer.executor.authorize = make_owner_authorization({
-                world: this.world,
-                identity_class: NetworkIdentity,
-                server_peer_id: this.local_peer_id,
-            });
-        }
-
-        // NetworkSystem handles slot_table allocation on NetworkIdentity attach.
-        // addSystem returns a promise that resolves once the system's own
-        // startup completes (it auto-starts when added to an already-Running
-        // EM). Await it so the session's identity observer below doesn't
-        // race with the NetworkSystem's observer over slot_table allocation.
-        await this.entity_manager.addSystem(new NetworkSystem(this.#peer));
-
-        // Sub-tick interpolation log: records per-frame replicated component
-        // state, sampled at render time for remotely-owned entities.
-        this.#interp_log = new InterpolationLog({
-            buffer_capacity_bytes: 65536,
-            records_capacity: 4096,
-        });
-
-        // Per-frame applied: snapshot all replicated components for each
-        // remote-owned entity into the interpolation log.
-        this.#peer.replicator.onFrameApplied.add((peer_id, frame_number) => {
-            this.#on_frame_applied(peer_id, frame_number);
-        });
-
-        // Initial-sync arrival (client only): store the session token,
-        // populate the world from the host's snapshot, resume normal
-        // action-stream processing, and finalize any in-flight Tier-3
-        // resync state.
-        if (this.role === NetworkSessionRole.Client) {
-            this.#peer.onInitialSync.add((_peer_id, session_token, _frame_number, buf, payload_end) => {
-                const token = new UUID();
-                token.data = session_token;
-                this.session_token = token;
-                this.#apply_initial_sync(buf, payload_end);
-                if (this.#reconnect_state === ReconnectState.Resyncing) {
-                    this.#enter_connected();
-                    this.onReconnected.send1({ state_resynced: true });
-                }
-            });
-            // Host's response to our RESUME_HELLO during reconnect.
-            this.#peer.onResumeAccept.add(() => {
-                if (this.#reconnect_state === ReconnectState.Reconnecting
-                    || this.#reconnect_state === ReconnectState.Resyncing) {
-                    this.#enter_connected();
-                    this.onReconnected.send1({ state_resynced: false });
-                }
-            });
-            this.#peer.onResumeReject.add((_peer_id, reason_code) => {
-                if (this.#reconnect_policy.accept_state_resync) {
-                    // Tier-3: drop unconfirmed predictions and wait for
-                    // the host to deliver a fresh INITIAL_SYNC.
-                    this.#sampled_actions_per_frame.clear();
-                    this.session_token = null;
-                    this.#reconnect_state = ReconnectState.Resyncing;
-                    // Restart the elapsed-ms budget so the Resyncing
-                    // watchdog (see #tick_reconnect) has a full
-                    // total_timeout_ms before falling to Lost.
-                    this.#reconnect_elapsed_ms = 0;
-                } else {
-                    this.#permanently_lose_connection(`resume_rejected:${reason_code}`);
-                }
-            });
-            // Host kicked us — final, no reconnect.
-            this.#peer.onDisconnectPacket.add((_peer_id, reason_label) => {
-                this.#permanently_lose_connection(reason_label || 'disconnected_by_host');
-            });
-        } else {
-            // Host: RESUME_HELLO validation + peer-initiated disconnects.
-            this.#peer.onResumeHello.add((peer_id, local_peer_id, last_acked_frame, session_token) => {
-                this.#on_resume_hello(peer_id, local_peer_id, last_acked_frame, session_token);
-            });
-            this.#peer.onDisconnectPacket.add((peer_id, reason_label) => {
-                // Client-initiated disconnect — skip the grace window
-                // and free state immediately.
-                this.drop_peer(peer_id, reason_label || 'client_disconnect');
-            });
-        }
-
-        // EntityObserver for NetworkIdentity: patches owner/network_id on
-        // attach, wires the per-entity mutation listener.
-        this.#identity_observer = new EntityObserver(
-            [NetworkIdentity],
-            (identity, entity_id) => this.#on_identity_attached(identity, entity_id),
-            (identity, entity_id) => this.#on_identity_detached(identity, entity_id),
-            this,
-        );
-        this.#identity_observer.connect(this.world);
-
-        this.#started = true;
-    }
-
-    /**
-     * Connect to a remote peer. Host can connect many peers (one per
-     * client); client typically connects one (the server). Called both
-     * for first-time connects and reconnect attempts — the session
-     * detects which based on whether a `session_token` is cached
-     * (client) or whether the peer is in the grace window (host).
-     *
-     * @param {number} remote_peer_id
-     * @param {object} transport
-     */
-    connect(remote_peer_id, transport) {
-        if (!this.#started) throw new Error("NetworkSession.connect: call start() first");
-
-        if (this.role === NetworkSessionRole.Host) {
-            const in_grace = this.#peer_grace_state.has(remote_peer_id);
-            this.#server.connect_peer(remote_peer_id, transport);
-            if (in_grace) {
-                // Resume candidate. Wait for RESUME_HELLO; restore
-                // baseline + add to connected_peers on validation.
-                // Don't queue INITIAL_SYNC — it'll only fire if we
-                // RESUME_REJECT.
-            } else {
-                // Fresh peer. Queue initial-sync for the next host tick.
-                this.#pending_initial_sync.set(remote_peer_id, 2);
-                this.#connected_peers.add(remote_peer_id);
-            }
-            this.#wire_peer_transport_disconnect(remote_peer_id, transport);
-        } else {
-            // Client
-            this.#client.connect_to_server(remote_peer_id, transport);
-            this.#remote_peer_id = remote_peer_id;
-            this.#current_transport = transport;
-            this.#wire_client_transport_disconnect(transport);
-            this.#connected_peers.add(remote_peer_id);
-
-            // If we have a session token cached, treat this as a
-            // reconnect attempt and send RESUME_HELLO immediately. A
-            // fresh session has no token yet (it arrives in the first
-            // INITIAL_SYNC), so first-time connects don't trigger this.
-            if (this.session_token !== null) {
-                const last_acked = Math.max(0, this.#latest_received_frame);
-                this.#peer.send_resume_hello(
-                    remote_peer_id, this.local_peer_id, last_acked,
-                    this.session_token.data,
-                );
-            }
-        }
-    }
-
-    /**
-     * Host-only: forcibly free a peer's state, regardless of whether
-     * they are actively connected, in the grace window, or already
-     * unknown. Fires `onPeerPermanentlyDropped(peer_id, reason)`.
-     * Sends a DISCONNECT packet if the peer is still actively
-     * connected so the remote can short-circuit its reconnect attempts.
-     *
-     * Policy for *when* to drop (high server load, anti-cheat, admin
-     * kick, etc.) is the caller's; the session provides the mechanism.
-     *
-     * @param {number} peer_id
-     * @param {string} [reason]
-     */
-    drop_peer(peer_id, reason = '') {
-        if (this.role !== NetworkSessionRole.Host) {
-            throw new Error("NetworkSession.drop_peer: host-only");
-        }
-        const was_connected = this.#connected_peers.has(peer_id);
-        const was_in_grace = this.#peer_grace_state.has(peer_id);
-        if (!was_connected && !was_in_grace) return;
-
-        if (was_connected) {
-            // Best-effort notification — peer may have already dropped.
-            try {
-                this.#peer.send_disconnect(peer_id, reason);
-            } catch (_) { /* swallow */
-            }
-            this.#server.disconnect_peer(peer_id);
-        }
-        this.#unwire_peer_transport_disconnect(peer_id);
-        this.#connected_peers.delete(peer_id);
-        this.#peer_inbound_mark.delete(peer_id);
-        this.#peer_grace_state.delete(peer_id);
-        this.#peer_session_tokens.delete(peer_id);
-        this.#pending_initial_sync.delete(peer_id);
-        this.onPeerPermanentlyDropped.send2(peer_id, reason);
-    }
-
-    /**
-     * Client-only: voluntarily disconnect from the server. Sends a
-     * DISCONNECT packet so the host can free state immediately and
-     * skip the grace window. Disables reconnect for this session.
-     *
-     * @param {string} [reason]
-     */
-    disconnect(reason = '') {
-        if (this.role !== NetworkSessionRole.Client) {
-            throw new Error("NetworkSession.disconnect: client-only — host uses drop_peer instead");
-        }
-        if (this.#remote_peer_id < 0) return;
-        const peer_id = this.#remote_peer_id;
-        try {
-            this.#peer.send_disconnect(peer_id, reason);
-        } catch (_) { /* swallow */
-        }
-        // Tear down the channel binding so a subsequent connect() with a
-        // fresh transport doesn't trip the underlying NetworkPeer's
-        // "peer already exists" guard. Mirrors the cleanup that
-        // #on_client_transport_disconnected does on an involuntary drop.
-        try {
-            this.#peer.disconnect_peer(peer_id);
-        } catch (_) { /* swallow */
-        }
-        // Drop the peer from the live send set so the (still-running) tick loop
-        // doesn't try to push empty-ack packets through the disposed channel.
-        this.#connected_peers.delete(peer_id);
-        this.#peer_inbound_mark.delete(peer_id);
-        if (this.#current_transport_listener !== null && this.#current_transport !== null) {
-            try {
-                this.#current_transport.onDisconnect.remove(this.#current_transport_listener);
-            } catch (_) { /* swallow */
-            }
-        }
-        this.#current_transport = null;
-        this.#current_transport_listener = null;
-        this.#remote_peer_id = -1;
-        this.#permanently_lose_connection(reason || 'client_disconnect');
-    }
-
-    /**
-     * Tear down. Idempotent — safe to call from cleanup paths.
-     */
-    stop() {
-        if (!this.#started) return;
-        if (this.#identity_observer !== null) {
-            this.#identity_observer.disconnect();
-            this.#identity_observer = null;
-        }
-        for (const [entity_id, listener] of this.#event_listeners) {
-            this.world.removeEntityEventListener(entity_id, "net_mutate_component", listener);
-        }
-        this.#event_listeners.clear();
-        this.#remote_entities.clear();
-        this.#sampled_actions_per_frame.clear();
-        this.#peer_inbound_mark.clear();
-        this.#started = false;
-    }
-
-    // ----------------------------------------------------------------
-    //  Per-tick driver
-    // ----------------------------------------------------------------
-
-    /**
-     * Fixed-timestep accumulator-driven step. Catch-up bounded by
-     * `MAX_FIXED_STEPS_PER_TICK`. Under `role: 'client'` the local frame
-     * advances at `1 / dilation_factor` per fixed step.
-     *
-     * @param {number} dt_seconds elapsed wall seconds since the previous call
-     */
-    tick(dt_seconds) {
-        if (!this.#started) return;
-
-        // Restore canonical form before sim work. The executor's
-        // `before_execute` hook also covers per-action paths (e.g.
-        // packets delivered between session.tick calls).
-        this.normalize_if_dirty();
-
-        const dt_ms = dt_seconds * 1000;
-
-        // Host: expire grace-window peers whose deadline has passed.
-        if (this.role === NetworkSessionRole.Host) {
-            this.#expire_grace_peers(performance.now());
-        } else {
-            // Client: drive the reconnect timer.
-            this.#tick_reconnect(dt_ms);
-        }
-
-        // Idle reaping: a connected peer that has gone silent past the timeout
-        // is reaped (host → grace, client → reconnect ladder). The clock is the
-        // deterministic tick-dt accumulator (not wall-clock), so it's testable.
-        if (this.#connection_timeout_ms > 0) {
-            this.#liveness_clock_ms += dt_ms;
-            this.#reap_silent_peers();
-        }
-
-        this.#sim_accum_ms += dt_ms;
-        let steps = 0;
-        while (this.#sim_accum_ms >= this.tick_period_ms && steps < MAX_FIXED_STEPS_PER_TICK) {
-            this.#sim_accum_ms -= this.tick_period_ms;
-            this.#simulate_one_step();
-            steps++;
-        }
-        if (steps === MAX_FIXED_STEPS_PER_TICK) this.#sim_accum_ms = 0;
-
-        // Per-render-frame: smooth interpolated rendering of remote
-        // entities. Marks the live ECD as polluted so the next sim-tick
-        // or reconcile starts with a normalize.
-        this.#render_interpolated_entities();
-    }
-
-    /**
-     * Undo render-time interpolation on remote-owned components by
-     * restoring each from its latest InterpolationLog entry. Idempotent
-     * via the `render_dirty` flag — cheap when false.
-     *
-     * Called from `tick()` (top), `executor.before_execute` (per-action
-     * applies, including transport-delivered action stream), and
-     * `client.onBeforeReconcile` (before the rewind walk).
-     *
-     * @private
-     */
-    normalize_if_dirty() {
-        if (!this.render_dirty) return;
-        this.render_dirty = false;
-
-        if (this.#latest_received_frame < 0) return;
-        if (this.#remote_entities.size === 0) return;
-
-        const scratch = this.#scratch_interp_buf;
-        const tick = this.#latest_received_frame;
-
-        for (const entity_id of this.#remote_entities) {
-            const identity = this.world.getComponent(entity_id, NetworkIdentity);
-            if (identity === undefined || identity.network_id < 0) continue;
-            for (const [ComponentClass, desc] of this.#replicated) {
-                if (desc.interp === null) continue;
-                const live = this.world.getComponent(entity_id, ComponentClass);
-                if (live === undefined) continue;
-                scratch.position = 0;
-                // tick_a === tick_b, t = 0 — degenerate "snap to single
-                // snapshot" lerp. Output equals the stored snapshot.
-                const ok = this.#interp_log.interpolate(
-                    scratch, identity.network_id, desc.interp_type_id,
-                    tick, tick, 0, desc.interp,
-                );
-                if (!ok) continue;
-                scratch.position = 0;
-                const adapter = this.binary_registry.getAdapter(ComponentClass.typeName);
-                adapter.deserialize(scratch, live);
-            }
-        }
-    }
-
-    /**
-     * Dispatch one user-defined action. Equivalent to
-     * `peer.executor.execute(action, this.local_peer_id)` but exposed
-     * at the session level so callers don't need a reference to the
-     * executor or to know the local peer id.
-     *
-     * @param {SimAction} action_instance
-     */
-    send(action_instance) {
-        if (!this.#started) throw new Error("NetworkSession.send: call start() first");
-        if (!action_instance || action_instance.isSimAction !== true) {
-            throw new Error("NetworkSession.send: argument must be a SimAction instance");
-        }
-        this.#peer.executor.execute(action_instance, this.local_peer_id);
-    }
-
-    // ----------------------------------------------------------------
-    //  Accessors
-    // ----------------------------------------------------------------
-
-    /**
-     * @returns {ServerAuthoritativeServer|null}
-     */
-    get server() {
-        return this.#server;
-    }
-
-    /**
-     * @returns {ServerAuthoritativeClient|null}
-     */
-    get client() {
-        return this.#client;
-    }
-
-    /**
-     * @returns {NetworkPeer|null}
-     */
-    get peer() {
-        return this.#peer;
-    }
-
-    /**
-     * @returns {InterpolationLog|null}
-     */
-    get interpolation_log() {
-        return this.#interp_log;
-    }
-
-    /**
-     * @returns {AdaptiveRenderDelay}
-     */
-    get adaptive_render_delay() {
-        return this.#adaptive_render_delay;
-    }
-
-    /**
-     * @returns {TimeDilation}
-     */
-    get time_dilation() {
-        return this.#time_dilation;
-    }
-
-    /**
-     * Most recent locally-completed sim frame.
-     */
-    get current_frame() {
-        if (this.role === NetworkSessionRole.Host) return this.#server.current_sim_frame;
-        return this.#local_frame - 1;
-    }
-
-    // ----------------------------------------------------------------
-    //  Internal: identity observer (component-driven spawn/despawn)
-    // ----------------------------------------------------------------
-
-    /**
-     * Patch `NetworkIdentity` on attach: `owner_peer_id` defaults to
-     * this session's `local_peer_id` if unset; `network_id` is assigned
-     * by {@link NetworkSystem.link}, which fires on the same attach.
-     *
-     * Callers must not mutate either field afterwards — the slot table
-     * and replicator cache them.
-     *
-     */
-    #on_identity_attached(identity, entity_id) {
-        if (identity.owner_peer_id < 0) {
-            identity.owner_peer_id = this.local_peer_id;
-        }
-        if (identity.owner_peer_id !== this.local_peer_id) {
-            this.#remote_entities.add(entity_id);
-        }
-        // Per-entity event listener for net_mutate_component.
-        const listener = (payload) => this.#on_net_mutate_component(entity_id, payload);
-        this.world.addEntityEventListener(entity_id, "net_mutate_component", listener);
-        this.#event_listeners.set(entity_id, listener);
-    }
-
-    #on_identity_detached(_identity, entity_id) {
-        const listener = this.#event_listeners.get(entity_id);
-        if (listener !== undefined) {
-            this.world.removeEntityEventListener(entity_id, "net_mutate_component", listener);
-            this.#event_listeners.delete(entity_id);
-        }
-        this.#remote_entities.delete(entity_id);
-    }
-
-    /**
-     * Handler for `"net_mutate_component"` events. Translates the payload
-     * into a `ReplaceComponentAction` and dispatches via the executor.
-     *
-     * Payload:
-     *   - `{ component_type, new_state }` — recommended; engine captures
-     *     current bytes as prior, then applies `new_state` via the
-     *     replication adapter.
-     *   - `{ component_type }` — caller has already mutated live; prior
-     *     bytes equal post bytes (rewind for this mutation is a no-op).
-     *
-     */
-    #on_net_mutate_component(entity_id, payload) {
-        const { component_type, new_state } = payload || {};
-        if (!component_type) {
-            throw new Error("net_mutate_component: payload must include `component_type`");
-        }
-        const desc = this.#replicated.get(component_type);
-        if (desc === undefined) {
-            throw new Error(`net_mutate_component: ${component_type.typeName ?? component_type.name} is not replicated; call session.replicate() for it before mutating`);
-        }
-
-        const network_id = this.#peer.slot_table.network_for(entity_id);
-        if (network_id < 0) return; // not networked yet
-
-        const live = this.world.getComponent(entity_id, component_type);
-        if (live === undefined) return;
-
-        const adapter = this.binary_registry.getAdapter(component_type.typeName);
-
-        // Build the action with the new-state bytes pre-baked. The
-        // executor will then capture the current `live` as prior bytes
-        // before action.apply deserializes new bytes into `live`.
-        const action = this.#peer.action_registry.acquire(this.#ReplaceComponentAction);
-        action.network_id = network_id;
-        action.component_type_id = desc.interp_type_id;
-        action.payload_buf.position = 0;
-        if (new_state !== undefined && new_state !== null) {
-            adapter.serialize(action.payload_buf, new_state);
-        } else {
-            // No new_state: live IS the new state.
-            adapter.serialize(action.payload_buf, live);
-        }
-        action.payload_length = action.payload_buf.position;
-
-        try {
-            this.#peer.executor.execute(action, this.local_peer_id);
-        } finally {
-            this.#peer.action_registry.release(action);
-        }
-    }
-
-    /**
-     * Build the synthetic ReplaceComponentAction class.
-     * The factory captures `interp_type_id_to_class` and `binary_registry` by
-     * reference so the inner class methods can resolve type ids and
-     * adapters without reaching into the outer class's private fields
-     * (which `#`-private syntax would forbid from a different class).
-     */
-    #make_replace_component_action_class() {
-        const interp_type_id_to_class = this.#interp_type_id_to_class;
-        const binary_registry = this.binary_registry;
-        return class ReplaceComponentAction extends SimAction {
-            constructor(network_id = 0, component_type_id = 0) {
-                super();
-                this.network_id = network_id;
-                this.component_type_id = component_type_id;
-                this.payload_buf = new BinaryBuffer();
-                this.payload_buf.setCapacity(SCRATCH_BUFFER_BYTES);
-                this.payload_length = 0;
-            }
-
-            apply(world, executor) {
-                const local = executor.slot_table.entity_for(this.network_id);
-                if (local < 0) return;
-                const ComponentClass = interp_type_id_to_class[this.component_type_id];
-                if (ComponentClass === undefined) return;
-                const live = world.getComponent(local, ComponentClass);
-                if (live === undefined) return;
-                const adapter = binary_registry.getAdapter(ComponentClass.typeName);
-                if (adapter === undefined) return;
-                this.payload_buf.position = 0;
-                adapter.deserialize(this.payload_buf, live);
-            }
-
-            affected_components(callback, executor) {
-                const local = executor.slot_table.entity_for(this.network_id);
-                if (local < 0) return;
-                const ComponentClass = interp_type_id_to_class[this.component_type_id];
-                if (ComponentClass === undefined) return;
-                callback(local, ComponentClass);
-            }
-
-            serialize(buffer) {
-                buffer.writeUintVar(this.network_id);
-                buffer.writeUint8(this.component_type_id);
-                buffer.writeUint32(this.payload_length);
-                if (this.payload_length > 0) {
-                    buffer.writeBytes(this.payload_buf.raw_bytes, 0, this.payload_length);
-                }
-            }
-
-            deserialize(buffer) {
-                this.network_id = buffer.readUintVar();
-                this.component_type_id = buffer.readUint8();
-                this.payload_length = buffer.readUint32();
-                if (this.payload_buf.raw_bytes.length < this.payload_length) {
-                    this.payload_buf.setCapacity(this.payload_length);
-                }
-                if (this.payload_length > 0) {
-                    buffer.readBytes(this.payload_buf.raw_bytes, 0, this.payload_length);
-                }
-                this.payload_buf.position = 0;
-            }
-
-            reset() {
-                this.network_id = 0;
-                this.component_type_id = 0;
-                this.payload_length = 0;
-                this.payload_buf.position = 0;
-            }
-        };
-    }
-
-    // ----------------------------------------------------------------
-    //  Internal: per-step simulation
-    // ----------------------------------------------------------------
-
-    #simulate_one_step() {
-        if (this.role === NetworkSessionRole.Host) {
-            this.#server.tick(this.#local_frame);
-            this.#local_frame++;
-            return;
-        }
-        // Client. Dilated tick rate: each fixed step advances by
-        // `1 / dilation_factor` (capped at MAX_CLIENT_DILATED_TICKS_PER_STEP).
-        this.#local_frame_accum += 1.0 / this.#client.dilation_factor;
-        let inner = 0;
-        while (this.#local_frame_accum >= 1.0 && inner < MAX_CLIENT_DILATED_TICKS_PER_STEP) {
-            this.#local_frame_accum -= 1.0;
-            this.#client.tick(this.#local_frame);
-            this.#send_empty_ack_packet();
-            this.#local_frame++;
-            inner++;
-        }
-    }
-
-    /**
-     * Empty action-stream packet to advance the channel's seq/ack
-     * baseline on ticks with no outbound actions of our own.
-     */
-    #send_empty_ack_packet() {
-        for (const peer_id of this.#connected_peers) {
-            this.#peer.channel_for(peer_id).send(EMPTY_PAYLOAD, 0);
-        }
-    }
-
-    // ----------------------------------------------------------------
-    //  Internal: host-side tick completion (AUTH_STATE + dilation feedback)
-    // ----------------------------------------------------------------
-
-    /**
-     *
-     * @param {number} sim_frame
-     */
-    #on_host_tick_complete(sim_frame) {
-        // Initial-sync first, so receivers have a populated world before
-        // AUTH_STATE / action-stream packets land.
-        if (this.#pending_initial_sync.size > 0) {
-
-            for (const [peer_id, sends_remaining] of this.#pending_initial_sync) {
-
-                this.#send_initial_sync_to(peer_id, sim_frame);
-
-                if (sends_remaining <= 1) {
-                    this.#pending_initial_sync.delete(peer_id);
-                } else {
-                    this.#pending_initial_sync.set(peer_id, sends_remaining - 1);
-                }
-
-            }
-
-        }
-
-        // AUTH_STATE per owned entity, then time-dilation feedback, to
-        // every connected peer.
-        for (const peer_id of this.#connected_peers) {
-
-            for (const entity_id of this.#event_listeners.keys()) {
-
-                const identity = this.world.getComponent(entity_id, NetworkIdentity);
-
-                if (identity === undefined) {
-                    continue;
-                }
-                if (identity.owner_peer_id !== peer_id) {
-                    continue;
-                }
-
-                this.#send_auth_state_for_entity(peer_id, sim_frame, entity_id, identity);
-
-            }
-
-            this.#server.send_time_dilation_feedback(peer_id);
-        }
-    }
-
-
-    /**
-     * Emit a Snapshotter-format payload to a freshly-connected peer.
-     * Generates and stashes a UUID v1 session token on first send,
-     * which the receiver echoes back via RESUME_HELLO to authenticate
-     * later reconnects.
-     * @param {number} peer_id
-     * @param {number} sim_frame
-     */
-    #send_initial_sync_to(peer_id, sim_frame) {
-        let token = this.#peer_session_tokens.get(peer_id);
-
-        if (token === undefined) {
-            token = UUID.v1();
-            this.#peer_session_tokens.set(peer_id, token);
-        }
-
-        this.#peer.send_initial_sync(peer_id, token.data, sim_frame, (buf) => {
-            snapshotter_emit({
-                buffer: buf,
-                world: this.world,
-                slot_table: this.#peer.slot_table,
-                component_registry: this.#peer.component_registry,
-                entity_iter: (cb) => {
-                    for (const entity_id of this.#event_listeners.keys()) {
-                        cb(entity_id);
-                    }
-                },
-            });
-        });
-    }
-
-    /**
-     * Apply an inbound INITIAL_SYNC payload. Walks the wire format
-     * directly instead of using `snapshotter_apply` so we can:
-     *   - Handle re-sync (slot already allocated) without
-     *     `slot_table.allocate_at` throwing.
-     *   - Let `NetworkSystem.link` handle slot allocation on the
-     *     NetworkIdentity-attach side-effect (NetworkIdentity is always
-     *     first in the stream).
-     *
-     */
-    #apply_initial_sync(buffer, payload_end) {
-        const entity_count = buffer.readUintVar();
-        for (let i = 0; i < entity_count; i++) {
-            const network_id = buffer.readUintVar();
-            const component_count = buffer.readUint8();
-            let local_entity_id = this.#peer.slot_table.entity_for(network_id);
-            if (local_entity_id < 0) {
-                local_entity_id = this.world.createEntity();
-            }
-
-            for (let j = 0; j < component_count; j++) {
-                const type_id = buffer.readUint8();
-                const payload_len = buffer.readUint32();
-                const ComponentClass = this.#peer.component_registry.class_of(type_id);
-                const adapter = this.#peer.component_registry.adapter_for_id(type_id);
-                if (ComponentClass === undefined || adapter === undefined) {
-                    buffer.position += payload_len;
-                    continue;
-                }
-                const existing = this.world.getComponent(local_entity_id, ComponentClass);
-                if (existing === undefined) {
-                    const component = new ComponentClass();
-                    adapter.deserialize(buffer, component);
-                    this.world.addComponentToEntity(local_entity_id, component);
-                } else {
-                    adapter.deserialize(buffer, existing);
-                }
-            }
-
-            if (buffer.position > payload_end) {
-                throw new Error(`NetworkSession.#apply_initial_sync: read past payload_end at network_id ${network_id}`);
-            }
-        }
-    }
-
-    /**
-     *
-     * @param {number} peer_id
-     * @param {number} sim_frame
-     * @param {number} entity_id
-     * @param {NetworkIdentity} identity
-     */
-    #send_auth_state_for_entity(peer_id, sim_frame, entity_id, identity) {
-        const network_id = identity.network_id;
-
-        if (network_id < 0) {
-            // not initialized
-            return;
-        }
-
-        this.#peer.send_auth_state(peer_id, sim_frame, network_id, (buf) => {
-
-            // Concatenate all replicated components in #replicated order.
-            for (const [ComponentClass, desc] of this.#replicated) {
-
-                const live = this.world.getComponent(entity_id, ComponentClass);
-
-                if (live === undefined) {
-                    continue;
-                }
-
-                const adapter = this.binary_registry.getAdapter(ComponentClass.typeName);
-
-                adapter.serialize(buf, live);
-
-            }
-
-        });
-    }
-
-    // ----------------------------------------------------------------
-    //  Internal: host-side reconnect / grace / drop machinery
-    // ----------------------------------------------------------------
-
-    #wire_peer_transport_disconnect(peer_id, transport) {
-        if (!transport || !transport.onDisconnect) return;
-        const listener = (reason) => this.#on_peer_transport_disconnected(peer_id, reason);
-        transport.onDisconnect.add(listener);
-        this.#peer_transport_listeners.set(peer_id, { transport, listener });
-    }
-
-    #unwire_peer_transport_disconnect(peer_id) {
-        const entry = this.#peer_transport_listeners.get(peer_id);
-        if (entry === undefined) return;
-        try {
-            entry.transport.onDisconnect.remove(entry.listener);
-        } catch (_) { /* swallow */
-        }
-        this.#peer_transport_listeners.delete(peer_id);
-    }
-
-    /**
-     * Move a peer into the grace window after its transport reports a
-     * disconnect. The peer's channel + baseline are torn down (so a
-     * subsequent `connect()` on a fresh transport doesn't collide), but
-     * the session token, slot-table entries, and `last_acked` watermark
-     * are preserved for the grace window. On expiry, `#expire_grace_peers`
-     * promotes the peer to fully-dropped.
-     */
-    #on_peer_transport_disconnected(peer_id, reason) {
-        if (!this.#connected_peers.has(peer_id)) return;
-        const last_acked = this.#peer.baseline.last_acked(peer_id);
-        this.#server.disconnect_peer(peer_id);
-        this.#connected_peers.delete(peer_id);
-        this.#peer_inbound_mark.delete(peer_id);
-        this.#unwire_peer_transport_disconnect(peer_id);
-        this.#peer_grace_state.set(peer_id, {
-            deadline_ms: performance.now() + this.#server_resume_grace_ms,
-            last_acked,
-        });
-        this.onPeerLost.send2(peer_id, reason);
-    }
-
-    /**
-     * Validate a RESUME_HELLO and either welcome the peer back (restore
-     * baseline + send RESUME_ACCEPT) or reject with a reason code.
-     * Rejection schedules a fresh INITIAL_SYNC so the client falls
-     * through to Tier-3.
-     */
-    #on_resume_hello(transport_peer_id, claimed_peer_id, last_acked_frame, claimed_token_bytes) {
-        // Engine convention: the matchmaking layer routes the reconnecting
-        // transport to the same `peer_id` it had before. If `claimed_peer_id`
-        // disagrees with `transport_peer_id`, the matchmaker mis-routed —
-        // treat as collision and kick the connection cleanly. Symmetric
-        // with the TokenMismatch path below: we MUST NOT leave the rogue
-        // transport wired to the dispatcher (any subsequent packet would
-        // still be routed), and we MUST NOT add them to the connected
-        // set or queue an INITIAL_SYNC.
-        if (transport_peer_id !== claimed_peer_id) {
-            this.#peer.send_resume_reject(transport_peer_id, ResumeRejectReason.PeerIdCollision);
-            this.#peer.send_disconnect(transport_peer_id, 'peer_id_collision');
-            this.#server.disconnect_peer(transport_peer_id);
-            this.#unwire_peer_transport_disconnect(transport_peer_id);
-            // The transport may have been added to the live set in connect()
-            // (a fresh peer connects, then sends a mis-routed RESUME_HELLO).
-            // Drop it from BOTH iterated maps — otherwise the next host tick
-            // serializes AUTH_STATE / time-dilation to a now-disposed conn and
-            // throws "peer not connected", taking down the tick for all peers.
-            this.#connected_peers.delete(transport_peer_id);
-            this.#pending_initial_sync.delete(transport_peer_id);
-            this.#peer_inbound_mark.delete(transport_peer_id);
-            return;
-        }
-        const grace = this.#peer_grace_state.get(claimed_peer_id);
-        if (grace === undefined) {
-            // Either the peer is fully unknown OR they're already
-            // connected (their previous transport never dropped).
-            // Either way, no resume record to validate against.
-            this.#peer.send_resume_reject(transport_peer_id, ResumeRejectReason.UnknownPeer);
-            // Treat as a fresh peer; schedule INITIAL_SYNC.
-            this.#pending_initial_sync.set(transport_peer_id, 2);
-            this.#connected_peers.add(transport_peer_id);
-            return;
-        }
-        const expected_token = this.#peer_session_tokens.get(claimed_peer_id);
-        if (expected_token === undefined) {
-            this.#peer.send_resume_reject(transport_peer_id, ResumeRejectReason.UnknownPeer);
-            this.#peer_grace_state.delete(claimed_peer_id);
-            this.#pending_initial_sync.set(transport_peer_id, 2);
-            this.#connected_peers.add(transport_peer_id);
-            return;
-        }
-        const claimed = new UUID();
-        claimed.data = claimed_token_bytes;
-        if (!claimed.equals(expected_token)) {
-            // Hard reject: a wrong-token attempt MUST NOT take over the
-            // legitimate peer's grace state (would let an attacker
-            // pre-empt the real owner's reconnect window) and MUST NOT
-            // be fresh-treated either (would expose the world via
-            // INITIAL_SYNC). Kick the connection; legitimate-but-
-            // corrupted-token clients fall to permanent-lost and need
-            // a new peer_id from the matchmaking layer.
-            this.#peer.send_resume_reject(transport_peer_id, ResumeRejectReason.TokenMismatch);
-            this.#peer.send_disconnect(transport_peer_id, 'token_mismatch');
-            this.#server.disconnect_peer(transport_peer_id);
-            this.#unwire_peer_transport_disconnect(transport_peer_id);
-            // Same cleanup as the collision branch above: if this transport was
-            // a fresh peer added to the live set, drop it from both iterated
-            // maps so the next host tick doesn't address a disposed conn.
-            this.#connected_peers.delete(transport_peer_id);
-            this.#pending_initial_sync.delete(transport_peer_id);
-            this.#peer_inbound_mark.delete(transport_peer_id);
-            return;
-        }
-        // Ring-floor gate. The client asks to resume from `last_acked_frame + 1`,
-        // but the action-log ring only still holds frames back to
-        // `current_sim_frame - frame_capacity + 1`. If the requested frame
-        // predates that floor, the frames needed to back-fill the gap have aged
-        // out — `pack_for_peer`'s has_frame guard would silently skip them and
-        // the client would enter `connected` missing in-scope mutations (a
-        // "successful" resume that runs visibly desynced). Reject so the client
-        // falls through to a full INITIAL_SYNC re-sync instead. Grace is
-        // typically far longer than the ring, so this is the routine case for
-        // any reconnect that took more than ~`frame_capacity` ticks.
-        const ring_floor = this.#server.current_sim_frame - this.frame_capacity + 1;
-        if (last_acked_frame + 1 < ring_floor) {
-            this.#peer.send_resume_reject(transport_peer_id, ResumeRejectReason.StaleFrame);
-            this.#peer_grace_state.delete(claimed_peer_id);
-            this.#pending_initial_sync.set(transport_peer_id, 2);
-            this.#connected_peers.add(transport_peer_id);
-            return;
-        }
-
-        // Valid resume. Restore the action-stream baseline so the
-        // replicator packs from `last_acked + 1`, then accept.
-        this.#peer.baseline.set_acked(claimed_peer_id, last_acked_frame);
-        this.#peer_grace_state.delete(claimed_peer_id);
-        this.#connected_peers.add(transport_peer_id);
-        this.#peer.send_resume_accept(transport_peer_id);
-    }
-
-    /**
-     * Walk the grace map and promote any peer whose deadline has
-     * passed to fully-dropped (fires `onPeerPermanentlyDropped`).
-     * Called from `tick()`.
-     */
-    #expire_grace_peers(now_ms) {
-        if (this.#peer_grace_state.size === 0) return;
-        for (const [peer_id, state] of this.#peer_grace_state) {
-            if (state.deadline_ms <= now_ms) {
-                this.#peer_grace_state.delete(peer_id);
-                this.#peer_session_tokens.delete(peer_id);
-                this.onPeerPermanentlyDropped.send2(peer_id, 'grace_expired');
-            }
-        }
-    }
-
-    /**
-     * Reap any connected peer whose inbound-packet count has not advanced for
-     * longer than `connection_timeout_ms`. Host-side peers go into the grace
-     * window (the same path a transport disconnect takes); the client routes a
-     * silent server into the reconnect ladder. Connectionless transports never
-     * emit a disconnect of their own, so without this a vanished peer would be
-     * pinned forever (host) or never noticed (client). The per-tick keepalive
-     * traffic the facade sends both directions keeps a live connection well
-     * clear of the budget. Called from `tick()` only when the budget is > 0.
-     * @private
-     */
-    #reap_silent_peers() {
-        if (this.role === NetworkSessionRole.Host) {
-            // Collect first — reaping mutates #connected_peers mid-iteration.
-            let to_reap = null;
-            for (const peer_id of this.#connected_peers) {
-                if (this.#peer_is_silent(peer_id)) (to_reap ??= []).push(peer_id);
-            }
-            if (to_reap !== null) {
-                for (let i = 0; i < to_reap.length; i++) {
-                    this.#on_peer_transport_disconnected(to_reap[i], 'timeout');
-                }
-            }
-        } else if (this.#reconnect_state === ReconnectState.Connected && this.#remote_peer_id >= 0) {
-            // Only when actively connected — Reconnecting/Resyncing have their
-            // own timers in #tick_reconnect.
-            if (this.#peer_is_silent(this.#remote_peer_id)) {
-                this.#on_client_transport_disconnected('timeout');
-            }
-        }
-    }
-
-    /**
-     * Whether `peer_id` has produced no inbound packet within the timeout
-     * budget. Maintains the per-peer mark as a side effect: resets the silence
-     * window whenever the peer's inbound count advances. A freshly-seen peer is
-     * stamped at the current clock and reported live, so it always gets a full
-     * budget before it can be reaped.
-     * @private
-     */
-    #peer_is_silent(peer_id) {
-        const count = this.#peer.inbound_count(peer_id);
-        const mark = this.#peer_inbound_mark.get(peer_id);
-        if (mark === undefined) {
-            this.#peer_inbound_mark.set(peer_id, { count, since_ms: this.#liveness_clock_ms });
-            return false;
-        }
-        if (count !== mark.count) {
-            mark.count = count;
-            mark.since_ms = this.#liveness_clock_ms;
-            return false;
-        }
-        return this.#liveness_clock_ms - mark.since_ms >= this.#connection_timeout_ms;
-    }
-
-    // ----------------------------------------------------------------
-    //  Internal: client-side reconnect state machine
-    // ----------------------------------------------------------------
-
-    #wire_client_transport_disconnect(transport) {
-        if (!transport || !transport.onDisconnect) return;
-        if (this.#current_transport_listener !== null && this.#current_transport !== null) {
-            try {
-                this.#current_transport.onDisconnect.remove(this.#current_transport_listener);
-            } catch (_) { /* swallow */
-            }
-        }
-        const listener = (reason) => this.#on_client_transport_disconnected(reason);
-        transport.onDisconnect.add(listener);
-        this.#current_transport_listener = listener;
-    }
-
-    #on_client_transport_disconnected(reason) {
-        if (this.#reconnect_state === ReconnectState.Lost) return;
-        // Tear down the dead peer/channel binding so a fresh transport
-        // can be wired via `connect()`. The InterpolationLog,
-        // session_token, predicted-action ledger, and live world all
-        // survive — that's what we need to claim continuity on resume.
-        if (this.#remote_peer_id >= 0) {
-            try {
-                this.#peer.disconnect_peer(this.#remote_peer_id);
-            } catch (_) { /* swallow */
-            }
-            // Stop treating this peer as a live send target. The channel is
-            // gone, but `#remote_peer_id` is deliberately kept so the reconnect
-            // ladder can re-`connect()` to the same id. Without this delete,
-            // `#send_empty_ack_packet` (driven every tick) dereferences the
-            // now-undefined channel and throws — which would crash the very
-            // tick loop that drives the reconnect ladder.
-            this.#connected_peers.delete(this.#remote_peer_id);
-            this.#peer_inbound_mark.delete(this.#remote_peer_id);
-        }
-        this.#current_transport = null;
-        this.#current_transport_listener = null;
-        if (!this.#reconnect_policy.enabled) {
-            this.#permanently_lose_connection(reason || 'transport_disconnect');
-            return;
-        }
-        this.#reconnect_state = ReconnectState.Reconnecting;
-        this.#reconnect_attempt = 0;
-        this.#reconnect_elapsed_ms = 0;
-        this.#reconnect_next_delay_ms = this.#reconnect_policy.base_delay_ms;
-        this.#reconnect_timer_remaining_ms = this.#reconnect_next_delay_ms;
-        this.onConnectionLost.send1(reason || 'transport_disconnect');
-    }
-
-    /**
-     * Per-tick advance for the client reconnect timer. When the timer
-     * elapses we rebuild the transport via `transport_factory` and
-     * call `connect()` on it; with a cached `session_token`, `connect`
-     * sends RESUME_HELLO. The server replies with RESUME_ACCEPT
-     * (→ Connected) or RESUME_REJECT (→ Resyncing, INITIAL_SYNC
-     * pending) or nothing within the next back-off interval (→ retry).
-     */
-    #tick_reconnect(dt_ms) {
-        // Resyncing has its own deadline: after RESUME_REJECT we expect
-        // the host to ship a fresh INITIAL_SYNC. If it never arrives
-        // (host crashed, network silently broke), fall to Lost so the
-        // application sees the failure instead of hanging forever.
-        if (this.#reconnect_state === ReconnectState.Resyncing) {
-            this.#reconnect_elapsed_ms += dt_ms;
-            if (this.#reconnect_elapsed_ms >= this.#reconnect_policy.total_timeout_ms) {
-                this.#permanently_lose_connection('resync_timeout');
-            }
-            return;
-        }
-        if (this.#reconnect_state !== ReconnectState.Reconnecting) return;
-        this.#reconnect_elapsed_ms += dt_ms;
-        if (this.#reconnect_elapsed_ms >= this.#reconnect_policy.total_timeout_ms) {
-            this.#permanently_lose_connection('reconnect_timeout');
-            return;
-        }
-        this.#reconnect_timer_remaining_ms -= dt_ms;
-        if (this.#reconnect_timer_remaining_ms > 0) return;
-
-        // Time to attempt.
-        this.#reconnect_attempt++;
-        if (this.#reconnect_attempt > this.#reconnect_policy.max_attempts) {
-            this.#permanently_lose_connection('reconnect_attempts_exhausted');
-            return;
-        }
-        this.onReconnectAttempt.send1(this.#reconnect_attempt);
-
-        if (this.#transport_factory === null) {
-            // No factory: caller must drive reconnects themselves. We
-            // remain in Reconnecting until they call connect() with a
-            // new transport, or until total_timeout_ms expires.
-            this.#reconnect_timer_remaining_ms = this.#next_backoff_delay();
-            return;
-        }
-        let new_transport;
-        try {
-            new_transport = this.#transport_factory();
-        } catch (e) {
-            console.warn('NetworkSession: transport_factory threw', e);
-            this.#reconnect_timer_remaining_ms = this.#next_backoff_delay();
-            return;
-        }
-        try {
-            this.connect(this.#remote_peer_id, new_transport);
-        } catch (e) {
-            console.warn('NetworkSession: connect() threw during reconnect', e);
-            this.#reconnect_timer_remaining_ms = this.#next_backoff_delay();
-            return;
-        }
-        // Wait the back-off interval before retrying again (if RESUME_ACCEPT
-        // never arrives in time).
-        this.#reconnect_timer_remaining_ms = this.#next_backoff_delay();
-    }
-
-    #next_backoff_delay() {
-        const next = this.#reconnect_next_delay_ms * this.#reconnect_policy.exponential_factor;
-        this.#reconnect_next_delay_ms = Math.min(next, this.#reconnect_policy.max_delay_ms);
-        return this.#reconnect_next_delay_ms;
-    }
-
-    #enter_connected() {
-        this.#reconnect_state = ReconnectState.Connected;
-        this.#reconnect_attempt = 0;
-        this.#reconnect_elapsed_ms = 0;
-        // Reset the exponential back-off so a subsequent disconnect starts
-        // its retry ladder from base_delay_ms — without this, the next drop
-        // would inherit the last cycle's (potentially max_delay_ms) delay.
-        this.#reconnect_next_delay_ms = this.#reconnect_policy.base_delay_ms;
-    }
-
-    #permanently_lose_connection(reason) {
-        if (this.#reconnect_state === ReconnectState.Lost) return;
-        this.#reconnect_state = ReconnectState.Lost;
-        this.onConnectionPermanentlyLost.send1(reason);
-    }
-
-    // ----------------------------------------------------------------
-    //  Internal: client predict-reconcile wiring
-    // ----------------------------------------------------------------
-
-    #wire_client_predict_reconcile() {
-        // Rewind doesn't go through executor.execute, so the
-        // before_execute normalize hook misses it. Catch it here.
-        this.#client.onBeforeReconcile.add(() => this.normalize_if_dirty());
-
-        // Predict: run the sampler, execute each action, record its
-        // bytes so the replay path can re-execute without re-sampling.
-        this.#client.onPredict.add((frame, _input_writer) => {
-            if (this.#input_sampler === null) return;
-            const actions = this.#input_sampler(frame);
-            if (!actions) return;
-            const recorded = [];
-            for (const action of actions) {
-                if (!action || action.isSimAction !== true) continue;
-                const type_id = action.constructor.type_id;
-                const scratch = this.#scratch_send_buf;
-                scratch.position = 0;
-                action.serialize(scratch);
-                const bytes = scratch.raw_bytes.slice(0, scratch.position);
-                recorded.push({ type_id, bytes });
-                this.#client.executor.execute(action, this.local_peer_id);
-            }
-            this.#sampled_actions_per_frame.set(frame, recorded);
-            this.#trim_sampled_action_ledger();
-        });
-
-        // Replay: re-execute recorded actions from the ledger. Sampler is
-        // NOT called again — live input has moved on.
-        this.#client.onReplay.add((frame, _input_reader) => {
-            const recorded = this.#sampled_actions_per_frame.get(frame);
-            if (!recorded) return;
-            for (const { type_id, bytes } of recorded) {
-                const klass = this.#peer.action_registry.klass_for(type_id);
-                if (klass === undefined) continue;
-                const action = this.#peer.action_registry.acquire(klass);
-                const scratch = this.#scratch_interp_buf;
-                scratch.position = 0;
-                scratch.writeBytes(bytes, 0, bytes.length);
-                scratch.position = 0;
-                action.deserialize(scratch);
-                try {
-                    this.#client.executor.execute(action, this.local_peer_id);
-                } finally {
-                    this.#peer.action_registry.release(action);
-                }
-            }
-        });
-
-        // Apply auth state: deserialize concatenated replicated-component
-        // bytes into the live entity. Mirrors the host's serialize order.
-        this.#client.onApplyAuthState.add((_server_frame, network_id, buffer) => {
-            const local = this.#client.slot_table.entity_for(network_id);
-            if (local < 0) return;
-            for (const [ComponentClass] of this.#replicated) {
-                const live = this.world.getComponent(local, ComponentClass);
-                if (live === undefined) continue;
-                const adapter = this.binary_registry.getAdapter(ComponentClass.typeName);
-                adapter.deserialize(buffer, live);
-            }
-        });
-    }
-
-    #trim_sampled_action_ledger() {
-        const action_log = this.#peer.action_log;
-        if (action_log === undefined) return;
-        const oldest_keep = Math.max(0, this.#local_frame - action_log.frame_capacity);
-        for (const f of this.#sampled_actions_per_frame.keys()) {
-            if (f < oldest_keep) this.#sampled_actions_per_frame.delete(f);
-        }
-    }
-
-    // ----------------------------------------------------------------
-    //  Internal: interpolation log + render-time sampling
-    // ----------------------------------------------------------------
-
-    /**
-     * Record post-apply state for every remote-owned entity into the
-     * interpolation log. Locally-owned entities are predicted, not
-     * interpolated, so they're skipped.
-     *
-     * Doesn't fire on the host — the replicator's deferral path doesn't
-     * emit `onFrameApplied`, so the host gets no recording naturally.
-     */
-    #on_frame_applied(_peer_id, frame_number) {
-        this.#interp_log.begin_tick(frame_number);
-        for (const entity_id of this.#remote_entities) {
-            const identity = this.world.getComponent(entity_id, NetworkIdentity);
-            if (identity === undefined || identity.network_id < 0) continue;
-            for (const [ComponentClass, desc] of this.#replicated) {
-                if (desc.interp === null) continue;
-                const live = this.world.getComponent(entity_id, ComponentClass);
-                if (live === undefined) continue;
-                const adapter = this.binary_registry.getAdapter(ComponentClass.typeName);
-                const rec_buf = this.#interp_log.begin_record(identity.network_id, desc.interp_type_id);
-                adapter.serialize(rec_buf, live);
-                this.#interp_log.end_record();
-            }
-        }
-        this.#interp_log.end_tick();
-
-        if (frame_number > this.#latest_received_frame) {
-            this.#adaptive_render_delay.record_arrival(performance.now(), frame_number);
-            this.#latest_received_frame = frame_number;
-        }
-    }
-
-    /**
-     * Advance the smooth_render_frame state machine and write
-     * interpolated bytes into each remote-owned entity's live
-     * components. Sets `render_dirty` if anything was written.
-     *
-     * Host early-returns naturally (no `#latest_received_frame`
-     * recorded — deferred-apply path doesn't fire `onFrameApplied`).
-     */
-    #render_interpolated_entities() {
-        if (this.#latest_received_frame < 0) return;
-        if (this.#remote_entities.size === 0) return;
-
-        const now_ms = performance.now();
-        const render_delay_frames = this.#adaptive_render_delay.delay_ms() / this.tick_period_ms;
-        const target = this.#latest_received_frame - render_delay_frames;
-
-        if (this.#smooth_render_frame < 0) {
-            this.#smooth_render_frame = target < 0 ? 0 : target;
-            this.#smooth_last_wall_ms = now_ms;
-        } else {
-            const dt_ms = now_ms - this.#smooth_last_wall_ms;
-            this.#smooth_last_wall_ms = now_ms;
-            this.#smooth_render_frame += dt_ms / this.tick_period_ms;
-            const alpha = 1 - Math.exp(-PULL_PER_MS * dt_ms);
-            this.#smooth_render_frame += (target - this.#smooth_render_frame) * alpha;
-        }
-        if (this.#smooth_render_frame > this.#latest_received_frame) {
-            this.#smooth_render_frame = this.#latest_received_frame;
-        }
-        if (this.#smooth_render_frame < 0) this.#smooth_render_frame = 0;
-
-        const tick_a = Math.floor(this.#smooth_render_frame);
-        const tick_b = tick_a + 1;
-        const t = this.#smooth_render_frame - tick_a;
-
-        const scratch = this.#scratch_interp_buf;
-        let wrote_anything = false;
-        for (const entity_id of this.#remote_entities) {
-            const identity = this.world.getComponent(entity_id, NetworkIdentity);
-            if (identity === undefined || identity.network_id < 0) continue;
-            for (const [ComponentClass, desc] of this.#replicated) {
-                if (desc.interp === null) continue; // snap mode
-                const live = this.world.getComponent(entity_id, ComponentClass);
-                if (live === undefined) continue;
-                scratch.position = 0;
-                const ok = this.#interp_log.interpolate(
-                    scratch, identity.network_id, desc.interp_type_id,
-                    tick_a, tick_b, t, desc.interp,
-                );
-                if (!ok) continue;
-                scratch.position = 0;
-                const adapter = this.binary_registry.getAdapter(ComponentClass.typeName);
-                adapter.deserialize(scratch, live);
-                wrote_anything = true;
-            }
-        }
-        if (wrote_anything) this.render_dirty = true;
-    }
-
-    // ----------------------------------------------------------------
-    //  Utility
-    // ----------------------------------------------------------------
-
-    #assert_not_started(method_name) {
-        if (this.#started) {
-            throw new Error(`NetworkSession.${method_name}: must be called before start()`);
-        }
-    }
-}
+import { assert } from "../../core/assert.js";
+import { BinaryBuffer } from "../../core/binary/BinaryBuffer.js";
+import Signal from "../../core/events/signal/Signal.js";
+import { EntityObserver } from "../ecs/EntityObserver.js";
+import { UUID } from "../ecs/guid/UUID.js";
+import { BinarySerializationRegistry, } from "../ecs/storage/binary/BinarySerializationRegistry.js";
+
+import { NetworkIdentity } from "./ecs/components/NetworkIdentity.js";
+import { make_owner_authorization } from "./ecs/owner_authorization.js";
+import { NetworkSystem } from "./ecs/NetworkSystem.js";
+import { NetworkIdentitySerializationAdapter, } from "./ecs/serialization/NetworkIdentitySerializationAdapter.js";
+import { NetworkPeer, ResumeRejectReason, } from "./orchestrator/NetworkPeer.js";
+import { ServerAuthoritativeClient } from "./orchestrator/ServerAuthoritativeClient.js";
+import { ServerAuthoritativeServer } from "./orchestrator/ServerAuthoritativeServer.js";
+import { OwnerAwareScope } from "./replication/ScopeFilter.js";
+import { BinaryInterpolationAdapter, InterpolationKind, } from "../interpolation/BinaryInterpolationAdapter.js";
+import { InterpolationLog } from "../interpolation/InterpolationLog.js";
+import { SimAction } from "./sim/SimAction.js";
+import { snapshotter_emit } from "./sim/Snapshotter.js";
+import { AdaptiveRenderDelay } from "./time/AdaptiveRenderDelay.js";
+import { TimeDilation } from "./time/TimeDilation.js";
+
+/**
+ * Roles a session can occupy. The orchestrator it wires up underneath is
+ * uniquely determined by the role.
+ *
+ *   - `'client'`  → {@link ServerAuthoritativeClient}: predicts locally
+ *                   when an input sampler is registered; reconciles to
+ *                   server-authoritative state arriving via AUTH_STATE.
+ *                   With no input sampler, a client is a pure spectator
+ *                   — it receives the action stream, smooths via
+ *                   interpolation, and never predicts or rewinds. This
+ *                   is the default role and covers both "playing" and
+ *                   "spectating" use cases.
+ *   - `'host'`    → {@link ServerAuthoritativeServer}: simulation
+ *                   authority for one or more clients; runs the optional
+ *                   server-side input buffer (`simulation_delay_ticks`).
+ *
+ * @readonly @enum {string}
+ */
+export const NetworkSessionRole = Object.freeze({
+    Client: 'client',
+    Host: 'host',
+});
+
+const DEFAULT_TICK_RATE_HZ = 60;
+const DEFAULT_SIMULATION_DELAY_TICKS = 4;
+const DEFAULT_INITIAL_RENDER_DELAY_FRAMES = 6;
+
+/**
+ * Default depth of the action-log ring (in frames). This single value bounds
+ * THREE distinct horizons at once:
+ *   1. Rollback depth — how far back the server can rewind+replay to fold in
+ *      late client input.
+ *   2. Fresh-connect back-fill range — how many past frames a newly-connected
+ *      peer's action stream covers before it has acked anything.
+ *   3. Action-stream retransmit window — how long an unacked frame stays
+ *      resendable before it ages out of the ring.
+ *
+ * At 60 Hz, 32 frames ≈ 0.53 s. That is comfortable for rollback but tight for
+ * loss recovery on high-latency links: if a peer's ack RTT + jitter exceeds the
+ * window, unacked frames age out and the action stream develops gaps that fall
+ * back to the heavier RECOVERY_REQUEST → STATE_BURST path. Raise `frame_capacity`
+ * for high-RTT / lossy deployments (memory cost is ~one buffer per frame per
+ * orchestrator, so it is cheap to grow).
+ */
+const DEFAULT_ACTION_LOG_FRAME_CAPACITY = 32;
+const PULL_PER_MS = 0.0005;        // wall-clock low-pass on render frame state machine
+const MAX_CLIENT_DILATED_TICKS_PER_STEP = 3;
+const MAX_FIXED_STEPS_PER_TICK = 8;
+
+const DEFAULT_SERVER_RESUME_GRACE_MS = 30_000;
+
+// Inbound-silence budget before a peer is reaped (host → grace, client →
+// reconnect ladder). Matches GNS's TimeoutConnected default. The facade pumps
+// at least one packet per tick in each direction (host: AUTH_STATE +
+// TIME_DILATION; client: action-stream / empty-ack), so a live, mutually-
+// ticking pair never approaches this — only a genuinely-gone peer does. Set 0
+// to disable (e.g. turn-based games, or transports that signal disconnect
+// themselves). Primarily for connectionless transports (NodeUDP, WebRTC /
+// WebTransport datagram), where no close event ever fires.
+const DEFAULT_CONNECTION_TIMEOUT_MS = 10_000;
+
+const DEFAULT_RECONNECT_POLICY = Object.freeze({
+    enabled: true,
+    max_attempts: 8,
+    base_delay_ms: 200,
+    max_delay_ms: 5_000,
+    exponential_factor: 2.0,
+    total_timeout_ms: 60_000,
+    accept_state_resync: true,
+});
+
+/**
+ * Client-side reconnect state machine values.
+ * @readonly @enum {string}
+ */
+const ReconnectState = Object.freeze({
+    Connected: 'connected',
+    Reconnecting: 'reconnecting',
+    Resyncing: 'resyncing',
+    Lost: 'lost',
+});
+
+/**
+ * Scratch buffer size used for AUTH_STATE assembly and net_mutate_component
+ * event payloads. Sized for the common cases (Transform ≈ 36 B); components
+ * with richer payloads need this raised or a different scratch lifecycle.
+ */
+const SCRATCH_BUFFER_BYTES = 1024;
+
+/**
+ * Shared zero-length payload for empty ack packets. Hoisted to module scope so
+ * the per-peer, per-tick ack send doesn't allocate a fresh array each time.
+ * @type {Uint8Array}
+ */
+const EMPTY_PAYLOAD = new Uint8Array(0);
+
+/**
+ * High-level networking facade. Wraps the orchestrator + state machinery
+ * into one config + lifecycle surface. The lower-level orchestrators
+ * remain reachable through `session.server` / `session.client` /
+ * `session.peer` for callers that need to override defaults post-hoc.
+ *
+ * Replication is component-driven: attaching a {@link NetworkIdentity}
+ * to an entity registers it with the session via an `EntityObserver`.
+ * Mutation is event-driven: callers fire
+ * `dataset.sendEvent(entity, "net_mutate_component", payload)`.
+ *
+ * Per-tick driving is a single `session.tick(dt_seconds)`. The session
+ * runs fixed-timestep stepping, client time dilation, server-side input
+ * buffer, AUTH_STATE dispatch, time-dilation feedback, and interpolated
+ * rendering for remote-owned entities.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class NetworkSession {
+
+    // ---- Pre-start registration (set via replicate / defineAction / defineInputSampler) ----
+
+    /**
+     * User-registered replicated component classes, in `replicate()` call
+     * order. Finalized at `start()` into {@link #replicated} with
+     * `NetworkIdentity` prepended.
+     * @private @type {Array<{klass: Function, interp: BinaryInterpolationAdapter|null}>}
+     */
+    #user_replicated = [];
+
+    /**
+     * Finalized at `start()`. Insertion order = wire-format order;
+     * `NetworkIdentity` is the first entry (its slot allocation must
+     * fire before subsequent components attach during initial-sync apply).
+     * Each value: `{ interp, interp_type_id }`.
+     * @private @type {Map<Function, {interp: BinaryInterpolationAdapter|null, interp_type_id: number}>}
+     */
+    #replicated = new Map();
+
+    /**
+     * Type_id → ComponentClass for the synthetic ReplaceComponentAction.
+     * @private @type {Function[]}
+     */
+    #interp_type_id_to_class = [];
+
+    /** @private @type {Array<Function>} */
+    #user_action_classes = [];
+
+    /** @private @type {((frame: number) => Array<SimAction>|null) | null} */
+    #input_sampler = null;
+
+    // ---- Set in start() ----
+
+    /** @private @type {ServerAuthoritativeServer|null} */
+    #server = null;
+    /** @private @type {ServerAuthoritativeClient|null} */
+    #client = null;
+    /** @private @type {NetworkPeer|null} */
+    #peer = null;
+    /** @private @type {EntityObserver|null} */
+    #identity_observer = null;
+    /** @private @type {InterpolationLog|null} */
+    #interp_log = null;
+    /** @private @type {Function|null} */
+    #ReplaceComponentAction = null;
+
+    // ---- Per-entity tracking ----
+
+    /**
+     * `entity_id → "net_mutate_component" listener` so detach can clean up.
+     * Also doubles as the iterable of all networked entities.
+     * @private @type {Map<number, Function>}
+     */
+    #event_listeners = new Map();
+
+    /**
+     * Entities the local peer does NOT own — driven by the render
+     * interpolation pass.
+     * @private @type {Set<number>}
+     */
+    #remote_entities = new Set();
+
+    // ---- Render-frame interpolation state ----
+
+    /** @private @type {number} */ #latest_received_frame = -1;
+    /** @private @type {number} */ #smooth_render_frame = -1;
+    /** @private @type {number} */ #smooth_last_wall_ms = -1;
+
+    /**
+     * Set after `#render_interpolated_entities` writes interp values into
+     * live components; cleared by `normalize_if_dirty`. Drives the
+     * canonical-form invariant: live is canonical when this is false,
+     * polluted (smooth) when true.
+     * @private @type {boolean}
+     */
+    render_dirty = false;
+
+    // ---- Per-tick driver state ----
+
+    /** @private @type {number} */ #local_frame = 0;
+    /** @private @type {number} */ #local_frame_accum = 0;
+    /** @private @type {number} */ #sim_accum_ms = 0;
+
+    /** @private @type {Set<number>} */
+    #connected_peers = new Set();
+
+    /**
+     * Host-only: peer_id → remaining-resends. Drained in
+     * `#on_host_tick_complete` once `current_sim_frame >= 0`. Sent twice
+     * for loss tolerance; production code should re-send on receiver
+     * RECOVERY request.
+     * @private @type {Map<number, number>}
+     */
+    #pending_initial_sync = new Map();
+
+    /**
+     * Sampled-action ledger for predict-reconcile replay. The sampler
+     * reads live input, so re-calling it during reconcile would give
+     * wrong results; replay reads from here instead.
+     * @private @type {Map<number, Array<{type_id: number, bytes: Uint8Array}>>}
+     */
+    #sampled_actions_per_frame = new Map();
+
+    /** @private @type {boolean} */
+    #started = false;
+
+    // ---- Host-side: per-peer session token + grace state ----
+
+    /**
+     * Tokens issued at first INITIAL_SYNC, kept while the peer is
+     * connected or in the grace window. Used to authenticate
+     * RESUME_HELLO.
+     * @private @type {Map<number, UUID>}
+     */
+    #peer_session_tokens = new Map();
+
+    /**
+     * Peers currently in the post-disconnect grace window. Value carries
+     * the deadline (wall-clock ms) and the cached `last_acked_frame` so
+     * a successful resume restores the action-stream baseline.
+     * @private @type {Map<number, { deadline_ms: number, last_acked: number }>}
+     */
+    #peer_grace_state = new Map();
+
+    /**
+     * Per-peer transport onDisconnect listener bookkeeping so we can
+     * unsubscribe when the peer is fully dropped.
+     * @private @type {Map<number, { transport: object, listener: Function }>}
+     */
+    #peer_transport_listeners = new Map();
+
+    // ---- Client-side: session token + reconnect state machine ----
+
+    /**
+     * Server-issued session token (raw UUID v1 bytes). Set on first
+     * INITIAL_SYNC arrival; refreshed on every Tier-3 resync. Sent in
+     * `RESUME_HELLO` to claim continuity with a prior session record.
+     * Observable to game code for diagnostics; not auth-grade.
+     * @type {UUID|null}
+     */
+    session_token = null;
+
+    /** @private @type {string} */
+    #reconnect_state = ReconnectState.Connected;
+    /** @private @type {number} */
+    #reconnect_attempt = 0;
+    /** @private @type {number} */
+    #reconnect_elapsed_ms = 0;
+    /** @private @type {number} */
+    #reconnect_next_delay_ms = 0;
+    /** @private @type {number} */
+    #reconnect_timer_remaining_ms = 0;
+    /** @private @type {object|null} */
+    #current_transport = null;
+    /** @private @type {Function|null} */
+    #current_transport_listener = null;
+    /** @private @type {number} */
+    #remote_peer_id = -1;
+
+    // ---- Signals (initialized inline because they take no input) ----
+
+    /**
+     * Host: a connected peer's transport reported a disconnect (the peer
+     * has entered the grace window). Args: `(peer_id, reason)`.
+     * @type {Signal}
+     */
+    onPeerLost = new Signal();
+
+    /**
+     * Host: a peer has been permanently freed — either via
+     * `drop_peer()`, a grace-window timeout, or a peer-initiated
+     * DISCONNECT. Args: `(peer_id, reason)`.
+     * @type {Signal}
+     */
+    onPeerPermanentlyDropped = new Signal();
+
+    /**
+     * Client: the transport has reported a disconnect, and the
+     * reconnect ladder has started. Args: `(reason)`.
+     * @type {Signal}
+     */
+    onConnectionLost = new Signal();
+
+    /**
+     * Client: about to rebuild the transport and dial the host. Args:
+     * `(attempt_number)`.
+     * @type {Signal}
+     */
+    onReconnectAttempt = new Signal();
+
+    /**
+     * Client: reconnect succeeded. Args: `({ state_resynced: boolean })` —
+     * `state_resynced` is `true` if we fell through to Tier-3 (server
+     * had purged our state and re-sent INITIAL_SYNC), `false` for the
+     * happy Tier-2 path where the action stream just resumed.
+     * @type {Signal}
+     */
+    onReconnected = new Signal();
+
+    /**
+     * Client: the reconnect ladder is exhausted, or the host explicitly
+     * kicked us with a DISCONNECT packet, or `reconnect.enabled` is
+     * false and the link dropped. Args: `(reason)`.
+     * @type {Signal}
+     */
+    onConnectionPermanentlyLost = new Signal();
+
+    // ---- Set in constructor (depend on input or imperative setup) ----
+
+    /** @private */ #transport = null;
+    /** @private */ #scope_filter = null;
+    /** @private @type {TimeDilation} */ #time_dilation;
+    /** @private @type {AdaptiveRenderDelay} */ #adaptive_render_delay;
+    /** @private @type {BinaryBuffer} */ #scratch_send_buf;
+    /** @private @type {BinaryBuffer} */ #scratch_interp_buf;
+    /** @private @type {() => void} */ #bound_normalize_if_dirty;
+
+    /** @private @type {number} */ #server_resume_grace_ms;
+    /** @private @type {object} */ #reconnect_policy;
+    /** @private @type {(() => object) | null} */ #transport_factory;
+
+    /** @private @type {number} ms of inbound silence before reaping; 0 = off */ #connection_timeout_ms;
+    /** @private @type {number} monotonic ms clock advanced by tick(dt) */ #liveness_clock_ms = 0;
+    /**
+     * Per-peer liveness mark: the inbound-packet count last seen and the clock
+     * time it was last seen advancing. Drives idle reaping.
+     * @private @type {Map<number, { count: number, since_ms: number }>}
+     */
+    #peer_inbound_mark = new Map();
+
+    /**
+     * @param {{
+     *   entity_manager: EntityManager,
+     *   transport?: object,
+     *   transport_factory?: (() => object),
+     *   role?: 'client'|'host',
+     *   local_peer_id?: number,
+     *   simulation_delay_ticks?: number,
+     *   tick_rate_hz?: number,
+     *   binary_registry?: BinarySerializationRegistry,
+     *   scope_filter?: object,
+     *   time_dilation?: TimeDilation,
+     *   adaptive_render_delay?: AdaptiveRenderDelay,
+     *   server_resume_grace_ms?: number,
+     *   connection_timeout_ms?: number,
+     *   reconnect?: {
+     *     enabled?: boolean,
+     *     max_attempts?: number,
+     *     base_delay_ms?: number,
+     *     max_delay_ms?: number,
+     *     exponential_factor?: number,
+     *     total_timeout_ms?: number,
+     *     accept_state_resync?: boolean,
+     *   },
+     * }} options
+     *
+     * - `transport` is not connected at construction — call {@link connect}
+     *   with an explicit remote peer id after {@link start}.
+     * - `transport_factory` (client role): zero-arg function that returns
+     *   a fresh `Transport` on each reconnect attempt. Required for
+     *   automatic reconnect; without it, transport-level disconnects fall
+     *   straight through to `onConnectionPermanentlyLost`.
+     * - `role` defaults to `'client'`. See {@link NetworkSessionRole}.
+     * - `local_peer_id` defaults to 0 for host, 1 for client. Must be
+     *   unique across peers.
+     * - `simulation_delay_ticks` is honored only under `role: 'host'`.
+     *   Default 4. See {@link ServerAuthoritativeServer}.
+     * - `tick_rate_hz` defaults to 60.
+     * - `frame_capacity` sizes the action-log ring (rollback depth + back-fill
+     *   range + retransmit window — see {@link DEFAULT_ACTION_LOG_FRAME_CAPACITY}).
+     *   Default 32. Raise it for high-RTT / lossy links.
+     * - `scope_filter` defaults to {@link OwnerAwareScope} on the host.
+     * - `server_resume_grace_ms` (host role): how long peer state is
+     *   retained after a transport drop before being freed. Default 30s.
+     * - `connection_timeout_ms`: inbound-silence budget before a peer is
+     *   reaped (host → grace, client → reconnect ladder). Default 10s; set 0
+     *   to disable. Mainly for connectionless transports, which never emit a
+     *   disconnect event — see {@link DEFAULT_CONNECTION_TIMEOUT_MS}.
+     * - `reconnect` (client role): policy for the reconnect ladder. See
+     *   {@link DEFAULT_RECONNECT_POLICY}. Set `enabled: false` to opt
+     *   out entirely.
+     */
+    constructor({
+                    entity_manager,
+                    transport = null,
+                    transport_factory = null,
+                    role = NetworkSessionRole.Client,
+                    local_peer_id = -1,
+                    simulation_delay_ticks = DEFAULT_SIMULATION_DELAY_TICKS,
+                    tick_rate_hz = DEFAULT_TICK_RATE_HZ,
+                    frame_capacity = DEFAULT_ACTION_LOG_FRAME_CAPACITY,
+                    binary_registry = null,
+                    scope_filter = null,
+                    time_dilation = null,
+                    adaptive_render_delay = null,
+                    server_resume_grace_ms = DEFAULT_SERVER_RESUME_GRACE_MS,
+                    connection_timeout_ms = DEFAULT_CONNECTION_TIMEOUT_MS,
+                    reconnect = null,
+                } = {}) {
+        assert.ok(entity_manager !== undefined && entity_manager !== null,
+            'NetworkSession: entity_manager is required');
+        if (role !== NetworkSessionRole.Client && role !== NetworkSessionRole.Host) {
+            throw new Error(`NetworkSession: invalid role '${role}'`);
+        }
+        assert.isNumber(tick_rate_hz, 'tick_rate_hz');
+        assert.ok(tick_rate_hz > 0, 'tick_rate_hz must be positive');
+        assert.isNonNegativeInteger(simulation_delay_ticks, 'simulation_delay_ticks');
+        assert.isPositiveInteger(frame_capacity, 'frame_capacity');
+
+        /**
+         * @readonly
+         * @type {EntityManager}
+         */
+        this.entity_manager = entity_manager;
+
+        /**
+         * @readonly
+         * @type {EntityComponentDataset}
+         */
+        this.world = entity_manager.dataset;
+
+        /**
+         * @readonly
+         * @type {NetworkSessionRole|string}
+         */
+        this.role = role;
+
+        /**
+         * @readonly
+         * @type {number}
+         */
+        this.tick_period_ms = 1000 / tick_rate_hz;
+
+        /**
+         * @readonly
+         * @type {number}
+         */
+        this.simulation_delay_ticks = role === NetworkSessionRole.Host
+            ? simulation_delay_ticks
+            : 0;
+
+        /**
+         * Depth of the action-log ring passed to the orchestrator. Bounds
+         * rollback depth, back-fill range, and retransmit window — see
+         * {@link DEFAULT_ACTION_LOG_FRAME_CAPACITY}.
+         * @readonly
+         * @type {number}
+         */
+        this.frame_capacity = frame_capacity;
+
+        /**
+         * @readonly
+         * @type {number}
+         */
+        this.local_peer_id = local_peer_id >= 0
+            ? local_peer_id
+            : (role === NetworkSessionRole.Host ? 0 : 1);
+
+        /**
+         * @readonly
+         * @type {BinarySerializationRegistry}
+         */
+        this.binary_registry = binary_registry || new BinarySerializationRegistry();
+
+        this.#transport = transport;
+        this.#scope_filter = scope_filter;
+
+        this.#time_dilation = time_dilation || new TimeDilation({
+            target_buffer_depth: this.simulation_delay_ticks > 0 ? this.simulation_delay_ticks : 2,
+            max_dilation: 0.05,
+            gain: 0.05,
+        });
+        this.#adaptive_render_delay = adaptive_render_delay || new AdaptiveRenderDelay({
+            tick_period_ms: this.tick_period_ms,
+            min_delay_frames: 2,
+            max_delay_frames: 30,
+            initial_delay_frames: DEFAULT_INITIAL_RENDER_DELAY_FRAMES,
+            history_size: 60,
+            safety_multiplier: 2.0,
+            decay_per_sample_ms: 1.0,
+        });
+
+        this.#scratch_send_buf = new BinaryBuffer();
+        this.#scratch_send_buf.setCapacity(SCRATCH_BUFFER_BYTES);
+
+        this.#scratch_interp_buf = new BinaryBuffer();
+        this.#scratch_interp_buf.setCapacity(SCRATCH_BUFFER_BYTES);
+
+        /**
+         * @type {() => void}
+         */
+        this.#bound_normalize_if_dirty = () => this.normalize_if_dirty();
+
+        this.#server_resume_grace_ms = server_resume_grace_ms;
+        assert.isNonNegativeInteger(connection_timeout_ms, 'connection_timeout_ms');
+        this.#connection_timeout_ms = connection_timeout_ms;
+        this.#reconnect_policy = Object.freeze({ ...DEFAULT_RECONNECT_POLICY, ...(reconnect || {}) });
+        this.#transport_factory = transport_factory;
+    }
+
+    // ----------------------------------------------------------------
+    //  Configuration (must run before start())
+    // ----------------------------------------------------------------
+
+    /**
+     * Register a component class for network replication.
+     *
+     * The component must have a {@link BinaryClassSerializationAdapter}
+     * registered for its `typeName` in the session's `binary_registry`
+     * before {@link start} is called — that adapter handles the wire
+     * format and rewind capture.
+     *
+     * `interpolator` is optional. When omitted, the component's state
+     * snaps on each received update (no sub-tick smoothing). When
+     * provided, it must extend {@link BinaryInterpolationAdapter} with
+     * `kind = InterpolationKind.Linear` — Discrete and Cubic are
+     * reserved for future support and currently throw.
+     *
+     * The order of `replicate()` calls must match across all peers in
+     * the session: AUTH_STATE payload layout iterates components in
+     * insertion order.
+     *
+     * @param {Function} ComponentClass
+     * @param {BinaryInterpolationAdapter} [interpolator]
+     */
+    replicate(ComponentClass, interpolator = null) {
+        this.#assert_not_started('replicate');
+        assert.isFunction(ComponentClass, 'ComponentClass');
+
+        if (ComponentClass === NetworkIdentity) {
+            throw new Error("NetworkSession.replicate: NetworkIdentity is auto-replicated; do not call replicate() for it");
+        }
+
+        for (const entry of this.#user_replicated) {
+            if (entry.klass === ComponentClass) {
+                throw new Error(`NetworkSession.replicate: ${ComponentClass.typeName ?? ComponentClass.name} already registered`);
+            }
+        }
+        if (interpolator !== null) {
+            if (!(interpolator instanceof BinaryInterpolationAdapter)) {
+                throw new Error("NetworkSession.replicate: interpolator must extend BinaryInterpolationAdapter");
+            }
+            if (interpolator.kind !== InterpolationKind.Linear) {
+                throw new Error(
+                    `NetworkSession.replicate: only Linear interpolation is currently supported; ` +
+                    `got kind=${interpolator.kind} for ${ComponentClass.typeName ?? ComponentClass.name}. ` +
+                    `Omit the interpolator argument for snap (Discrete) behavior; Cubic is reserved.`,
+                );
+            }
+        }
+        this.#user_replicated.push({ klass: ComponentClass, interp: interpolator });
+    }
+
+    /**
+     * Register a user-defined {@link SimAction} subclass with the
+     * session. The action's `type_id` is assigned by the underlying
+     * registry when {@link start} runs. Calling code constructs
+     * instances directly (`new MyAction(...)`) and dispatches via
+     * {@link send} or returns them from the input sampler.
+     *
+     * @param {Function} SimActionClass class extending SimAction
+     */
+    defineAction(SimActionClass) {
+        this.#assert_not_started('defineAction');
+        assert.isFunction(SimActionClass, 'SimActionClass');
+        this.#user_action_classes.push(SimActionClass);
+    }
+
+    /**
+     * Install a per-tick input sampler (client role only). The sampler
+     * is called once per local sim tick at predict time and must return
+     * an array of {@link SimAction} instances representing the local
+     * peer's inputs for that frame. The session executes them locally
+     * (predict), records their serialized bytes for replay, and forwards
+     * them over the action stream.
+     *
+     * The sampler is NOT called during reconciliation replay — the
+     * recorded bytes are deserialized and re-executed instead, so the
+     * action set faithfully reproduces what the user originally
+     * sampled at that frame.
+     *
+     * Return `[]` (or `null`) for ticks with no inputs.
+     *
+     * @param {(frame: number) => Array<SimAction>|null} sampler_fn
+     */
+    defineInputSampler(sampler_fn) {
+        this.#assert_not_started('defineInputSampler');
+        assert.isFunction(sampler_fn, 'sampler_fn');
+
+        if (this.role !== NetworkSessionRole.Client) {
+            throw new Error(`NetworkSession.defineInputSampler: only valid for role='${NetworkSessionRole.Client}', got '${this.role}'`);
+        }
+
+        this.#input_sampler = sampler_fn;
+    }
+
+    // ----------------------------------------------------------------
+    //  Lifecycle
+    // ----------------------------------------------------------------
+
+    /**
+     * Wire the session to the engine. After this, the EntityObserver
+     * is active, the right orchestrator is constructed, and a
+     * {@link NetworkSystem} is attached. Subsequent {@link replicate}
+     * / {@link defineAction} / {@link defineInputSampler} calls throw.
+     *
+     * Pre-condition: every component class passed to {@link replicate}
+     * must already have a `BinaryClassSerializationAdapter` registered
+     * in the session's binary_registry.
+     */
+    async start() {
+        if (this.#started) throw new Error("NetworkSession.start: already started");
+
+        // Auto-register the NetworkIdentity adapter so initial-sync can
+        // ship it across the wire. Allow caller-supplied registrations
+        // to win (game might have a custom one).
+        if (this.binary_registry.getAdapter(NetworkIdentity.typeName) === undefined) {
+            this.binary_registry.registerAdapter(new NetworkIdentitySerializationAdapter(), NetworkIdentity.typeName);
+        }
+
+        // Finalize the replicated-components ordering: NetworkIdentity
+        // FIRST (so it gets type_id=0 and arrives as the first per-entity
+        // record in snapshots — receiver attaches NetworkIdentity first,
+        // which triggers slot-table allocation before any other component
+        // payload needs to look up `entity_for(network_id)`).
+        let next_id = 0;
+        const network_identity_scratch = new BinaryBuffer();
+        network_identity_scratch.setCapacity(SCRATCH_BUFFER_BYTES);
+        this.#replicated.set(NetworkIdentity, {
+            interp: null,
+            interp_type_id: next_id++,
+        });
+        this.#interp_type_id_to_class[0] = NetworkIdentity;
+        for (const { klass, interp } of this.#user_replicated) {
+            const interp_type_id = next_id++;
+            this.#replicated.set(klass, { interp, interp_type_id });
+            this.#interp_type_id_to_class[interp_type_id] = klass;
+        }
+
+        // Verify each replicated component has a serialization adapter.
+        for (const ComponentClass of this.#replicated.keys()) {
+            const name = ComponentClass.typeName;
+            if (typeof name !== 'string') {
+                throw new Error(`NetworkSession.start: ${ComponentClass.name} has no static .typeName; cannot look up its adapter`);
+            }
+            if (this.binary_registry.getAdapter(name) === undefined) {
+                throw new Error(`NetworkSession.start: no BinaryClassSerializationAdapter registered for ${name}; register one in the binary_registry before calling start()`);
+            }
+        }
+
+        // Build the synthetic ReplaceComponentAction now so it's in the
+        // action_classes list when the orchestrator is constructed.
+        this.#ReplaceComponentAction = this.#make_replace_component_action_class();
+
+        const replicated_components = Array.from(this.#replicated.keys());
+        const action_classes = [...this.#user_action_classes, this.#ReplaceComponentAction];
+
+        const orchestrator_opts = {
+            world: this.world,
+            binary_registry: this.binary_registry,
+            replicated_components,
+            action_classes,
+            frame_capacity: this.frame_capacity,
+        };
+
+        if (this.role === NetworkSessionRole.Host) {
+            this.#server = new ServerAuthoritativeServer({
+                ...orchestrator_opts,
+                simulation_delay_ticks: this.simulation_delay_ticks,
+            });
+            this.#peer = this.#server.peer;
+            this.#peer.replicator.scope_filter = this.#scope_filter || new OwnerAwareScope({
+                world: this.world,
+                slot_table: this.#server.slot_table,
+                identity_class: NetworkIdentity,
+            });
+            this.#server.onTickComplete.add((sim_frame) => this.#on_host_tick_complete(sim_frame));
+        } else {
+            // Client role: covers both "playing" (input sampler registered)
+            // and "spectator" (no sampler — sampler-driven onPredict
+            // returns no actions, so the predict-reconcile machinery
+            // exists but stays idle).
+            this.#client = new ServerAuthoritativeClient({
+                ...orchestrator_opts,
+                time_dilation: this.#time_dilation,
+            });
+            this.#peer = this.#client.peer;
+            if (this.#scope_filter) {
+                this.#peer.replicator.scope_filter = this.#scope_filter;
+            }
+            this.#wire_client_predict_reconcile();
+        }
+
+        // Install the canonical-form normalize hook on the executor.
+        // Anything that calls executor.execute — predict apply, action-
+        // stream apply, reconcile replay — first normalizes the world.
+        // Idempotent: cheap when `render_dirty` is false (one bool
+        // check), expensive (one adapter.deserialize per remote-owned
+        // component) only on the first execute after a render pass.
+        this.#peer.executor.before_execute = this.#bound_normalize_if_dirty;
+
+        // Secure-by-default inbound authorization on the host: a remote client
+        // may only mutate entities it owns (NetworkIdentity.owner_peer_id ===
+        // sender); the authoritative server (sender === local_peer_id) may
+        // mutate anything. Without this a connected peer can craft an action
+        // targeting another peer's (or a server-owned) entity. Games needing a
+        // different policy can overwrite executor.authorize after start().
+        // Client sessions trust the server's stream and so are not gated.
+        if (this.role === NetworkSessionRole.Host) {
+            this.#peer.executor.authorize = make_owner_authorization({
+                world: this.world,
+                identity_class: NetworkIdentity,
+                server_peer_id: this.local_peer_id,
+            });
+        }
+
+        // NetworkSystem handles slot_table allocation on NetworkIdentity attach.
+        // addSystem returns a promise that resolves once the system's own
+        // startup completes (it auto-starts when added to an already-Running
+        // EM). Await it so the session's identity observer below doesn't
+        // race with the NetworkSystem's observer over slot_table allocation.
+        await this.entity_manager.addSystem(new NetworkSystem(this.#peer));
+
+        // Sub-tick interpolation log: records per-frame replicated component
+        // state, sampled at render time for remotely-owned entities.
+        this.#interp_log = new InterpolationLog({
+            buffer_capacity_bytes: 65536,
+            records_capacity: 4096,
+        });
+
+        // Per-frame applied: snapshot all replicated components for each
+        // remote-owned entity into the interpolation log.
+        this.#peer.replicator.onFrameApplied.add((peer_id, frame_number) => {
+            this.#on_frame_applied(peer_id, frame_number);
+        });
+
+        // Initial-sync arrival (client only): store the session token,
+        // populate the world from the host's snapshot, resume normal
+        // action-stream processing, and finalize any in-flight Tier-3
+        // resync state.
+        if (this.role === NetworkSessionRole.Client) {
+            this.#peer.onInitialSync.add((_peer_id, session_token, _frame_number, buf, payload_end) => {
+                const token = new UUID();
+                token.data = session_token;
+                this.session_token = token;
+                this.#apply_initial_sync(buf, payload_end);
+                if (this.#reconnect_state === ReconnectState.Resyncing) {
+                    this.#enter_connected();
+                    this.onReconnected.send1({ state_resynced: true });
+                }
+            });
+            // Host's response to our RESUME_HELLO during reconnect.
+            this.#peer.onResumeAccept.add(() => {
+                if (this.#reconnect_state === ReconnectState.Reconnecting
+                    || this.#reconnect_state === ReconnectState.Resyncing) {
+                    this.#enter_connected();
+                    this.onReconnected.send1({ state_resynced: false });
+                }
+            });
+            this.#peer.onResumeReject.add((_peer_id, reason_code) => {
+                if (this.#reconnect_policy.accept_state_resync) {
+                    // Tier-3: drop unconfirmed predictions and wait for
+                    // the host to deliver a fresh INITIAL_SYNC.
+                    this.#sampled_actions_per_frame.clear();
+                    this.session_token = null;
+                    this.#reconnect_state = ReconnectState.Resyncing;
+                    // Restart the elapsed-ms budget so the Resyncing
+                    // watchdog (see #tick_reconnect) has a full
+                    // total_timeout_ms before falling to Lost.
+                    this.#reconnect_elapsed_ms = 0;
+                } else {
+                    this.#permanently_lose_connection(`resume_rejected:${reason_code}`);
+                }
+            });
+            // Host kicked us — final, no reconnect.
+            this.#peer.onDisconnectPacket.add((_peer_id, reason_label) => {
+                this.#permanently_lose_connection(reason_label || 'disconnected_by_host');
+            });
+        } else {
+            // Host: RESUME_HELLO validation + peer-initiated disconnects.
+            this.#peer.onResumeHello.add((peer_id, local_peer_id, last_acked_frame, session_token) => {
+                this.#on_resume_hello(peer_id, local_peer_id, last_acked_frame, session_token);
+            });
+            this.#peer.onDisconnectPacket.add((peer_id, reason_label) => {
+                // Client-initiated disconnect — skip the grace window
+                // and free state immediately.
+                this.drop_peer(peer_id, reason_label || 'client_disconnect');
+            });
+        }
+
+        // EntityObserver for NetworkIdentity: patches owner/network_id on
+        // attach, wires the per-entity mutation listener.
+        this.#identity_observer = new EntityObserver(
+            [NetworkIdentity],
+            (identity, entity_id) => this.#on_identity_attached(identity, entity_id),
+            (identity, entity_id) => this.#on_identity_detached(identity, entity_id),
+            this,
+        );
+        this.#identity_observer.connect(this.world);
+
+        this.#started = true;
+    }
+
+    /**
+     * Connect to a remote peer. Host can connect many peers (one per
+     * client); client typically connects one (the server). Called both
+     * for first-time connects and reconnect attempts — the session
+     * detects which based on whether a `session_token` is cached
+     * (client) or whether the peer is in the grace window (host).
+     *
+     * @param {number} remote_peer_id
+     * @param {object} transport
+     */
+    connect(remote_peer_id, transport) {
+        if (!this.#started) throw new Error("NetworkSession.connect: call start() first");
+
+        if (this.role === NetworkSessionRole.Host) {
+            const in_grace = this.#peer_grace_state.has(remote_peer_id);
+            this.#server.connect_peer(remote_peer_id, transport);
+            if (in_grace) {
+                // Resume candidate. Wait for RESUME_HELLO; restore
+                // baseline + add to connected_peers on validation.
+                // Don't queue INITIAL_SYNC — it'll only fire if we
+                // RESUME_REJECT.
+            } else {
+                // Fresh peer. Queue initial-sync for the next host tick.
+                this.#pending_initial_sync.set(remote_peer_id, 2);
+                this.#connected_peers.add(remote_peer_id);
+            }
+            this.#wire_peer_transport_disconnect(remote_peer_id, transport);
+        } else {
+            // Client
+            this.#client.connect_to_server(remote_peer_id, transport);
+            this.#remote_peer_id = remote_peer_id;
+            this.#current_transport = transport;
+            this.#wire_client_transport_disconnect(transport);
+            this.#connected_peers.add(remote_peer_id);
+
+            // If we have a session token cached, treat this as a
+            // reconnect attempt and send RESUME_HELLO immediately. A
+            // fresh session has no token yet (it arrives in the first
+            // INITIAL_SYNC), so first-time connects don't trigger this.
+            if (this.session_token !== null) {
+                const last_acked = Math.max(0, this.#latest_received_frame);
+                this.#peer.send_resume_hello(
+                    remote_peer_id, this.local_peer_id, last_acked,
+                    this.session_token.data,
+                );
+            }
+        }
+    }
+
+    /**
+     * Host-only: forcibly free a peer's state, regardless of whether
+     * they are actively connected, in the grace window, or already
+     * unknown. Fires `onPeerPermanentlyDropped(peer_id, reason)`.
+     * Sends a DISCONNECT packet if the peer is still actively
+     * connected so the remote can short-circuit its reconnect attempts.
+     *
+     * Policy for *when* to drop (high server load, anti-cheat, admin
+     * kick, etc.) is the caller's; the session provides the mechanism.
+     *
+     * @param {number} peer_id
+     * @param {string} [reason]
+     */
+    drop_peer(peer_id, reason = '') {
+        if (this.role !== NetworkSessionRole.Host) {
+            throw new Error("NetworkSession.drop_peer: host-only");
+        }
+        const was_connected = this.#connected_peers.has(peer_id);
+        const was_in_grace = this.#peer_grace_state.has(peer_id);
+        if (!was_connected && !was_in_grace) return;
+
+        if (was_connected) {
+            // Best-effort notification — peer may have already dropped.
+            try {
+                this.#peer.send_disconnect(peer_id, reason);
+            } catch (_) { /* swallow */
+            }
+            this.#server.disconnect_peer(peer_id);
+        }
+        this.#unwire_peer_transport_disconnect(peer_id);
+        this.#connected_peers.delete(peer_id);
+        this.#peer_inbound_mark.delete(peer_id);
+        this.#peer_grace_state.delete(peer_id);
+        this.#peer_session_tokens.delete(peer_id);
+        this.#pending_initial_sync.delete(peer_id);
+        this.onPeerPermanentlyDropped.send2(peer_id, reason);
+    }
+
+    /**
+     * Client-only: voluntarily disconnect from the server. Sends a
+     * DISCONNECT packet so the host can free state immediately and
+     * skip the grace window. Disables reconnect for this session.
+     *
+     * @param {string} [reason]
+     */
+    disconnect(reason = '') {
+        if (this.role !== NetworkSessionRole.Client) {
+            throw new Error("NetworkSession.disconnect: client-only — host uses drop_peer instead");
+        }
+        if (this.#remote_peer_id < 0) return;
+        const peer_id = this.#remote_peer_id;
+        try {
+            this.#peer.send_disconnect(peer_id, reason);
+        } catch (_) { /* swallow */
+        }
+        // Tear down the channel binding so a subsequent connect() with a
+        // fresh transport doesn't trip the underlying NetworkPeer's
+        // "peer already exists" guard. Mirrors the cleanup that
+        // #on_client_transport_disconnected does on an involuntary drop.
+        try {
+            this.#peer.disconnect_peer(peer_id);
+        } catch (_) { /* swallow */
+        }
+        // Drop the peer from the live send set so the (still-running) tick loop
+        // doesn't try to push empty-ack packets through the disposed channel.
+        this.#connected_peers.delete(peer_id);
+        this.#peer_inbound_mark.delete(peer_id);
+        if (this.#current_transport_listener !== null && this.#current_transport !== null) {
+            try {
+                this.#current_transport.onDisconnect.remove(this.#current_transport_listener);
+            } catch (_) { /* swallow */
+            }
+        }
+        this.#current_transport = null;
+        this.#current_transport_listener = null;
+        this.#remote_peer_id = -1;
+        this.#permanently_lose_connection(reason || 'client_disconnect');
+    }
+
+    /**
+     * Tear down. Idempotent — safe to call from cleanup paths.
+     */
+    stop() {
+        if (!this.#started) return;
+        if (this.#identity_observer !== null) {
+            this.#identity_observer.disconnect();
+            this.#identity_observer = null;
+        }
+        for (const [entity_id, listener] of this.#event_listeners) {
+            this.world.removeEntityEventListener(entity_id, "net_mutate_component", listener);
+        }
+        this.#event_listeners.clear();
+        this.#remote_entities.clear();
+        this.#sampled_actions_per_frame.clear();
+        this.#peer_inbound_mark.clear();
+        this.#started = false;
+    }
+
+    // ----------------------------------------------------------------
+    //  Per-tick driver
+    // ----------------------------------------------------------------
+
+    /**
+     * Fixed-timestep accumulator-driven step. Catch-up bounded by
+     * `MAX_FIXED_STEPS_PER_TICK`. Under `role: 'client'` the local frame
+     * advances at `1 / dilation_factor` per fixed step.
+     *
+     * @param {number} dt_seconds elapsed wall seconds since the previous call
+     */
+    tick(dt_seconds) {
+        if (!this.#started) return;
+
+        // Restore canonical form before sim work. The executor's
+        // `before_execute` hook also covers per-action paths (e.g.
+        // packets delivered between session.tick calls).
+        this.normalize_if_dirty();
+
+        const dt_ms = dt_seconds * 1000;
+
+        // Host: expire grace-window peers whose deadline has passed.
+        if (this.role === NetworkSessionRole.Host) {
+            this.#expire_grace_peers(performance.now());
+        } else {
+            // Client: drive the reconnect timer.
+            this.#tick_reconnect(dt_ms);
+        }
+
+        // Idle reaping: a connected peer that has gone silent past the timeout
+        // is reaped (host → grace, client → reconnect ladder). The clock is the
+        // deterministic tick-dt accumulator (not wall-clock), so it's testable.
+        if (this.#connection_timeout_ms > 0) {
+            this.#liveness_clock_ms += dt_ms;
+            this.#reap_silent_peers();
+        }
+
+        this.#sim_accum_ms += dt_ms;
+        let steps = 0;
+        while (this.#sim_accum_ms >= this.tick_period_ms && steps < MAX_FIXED_STEPS_PER_TICK) {
+            this.#sim_accum_ms -= this.tick_period_ms;
+            this.#simulate_one_step();
+            steps++;
+        }
+        if (steps === MAX_FIXED_STEPS_PER_TICK) this.#sim_accum_ms = 0;
+
+        // Per-render-frame: smooth interpolated rendering of remote
+        // entities. Marks the live ECD as polluted so the next sim-tick
+        // or reconcile starts with a normalize.
+        this.#render_interpolated_entities();
+    }
+
+    /**
+     * Undo render-time interpolation on remote-owned components by
+     * restoring each from its latest InterpolationLog entry. Idempotent
+     * via the `render_dirty` flag — cheap when false.
+     *
+     * Called from `tick()` (top), `executor.before_execute` (per-action
+     * applies, including transport-delivered action stream), and
+     * `client.onBeforeReconcile` (before the rewind walk).
+     *
+     * @private
+     */
+    normalize_if_dirty() {
+        if (!this.render_dirty) return;
+        this.render_dirty = false;
+
+        if (this.#latest_received_frame < 0) return;
+        if (this.#remote_entities.size === 0) return;
+
+        const scratch = this.#scratch_interp_buf;
+        const tick = this.#latest_received_frame;
+
+        for (const entity_id of this.#remote_entities) {
+            const identity = this.world.getComponent(entity_id, NetworkIdentity);
+            if (identity === undefined || identity.network_id < 0) continue;
+            for (const [ComponentClass, desc] of this.#replicated) {
+                if (desc.interp === null) continue;
+                const live = this.world.getComponent(entity_id, ComponentClass);
+                if (live === undefined) continue;
+                scratch.position = 0;
+                // tick_a === tick_b, t = 0 — degenerate "snap to single
+                // snapshot" lerp. Output equals the stored snapshot.
+                const ok = this.#interp_log.interpolate(
+                    scratch, identity.network_id, desc.interp_type_id,
+                    tick, tick, 0, desc.interp,
+                );
+                if (!ok) continue;
+                scratch.position = 0;
+                const adapter = this.binary_registry.getAdapter(ComponentClass.typeName);
+                adapter.deserialize(scratch, live);
+            }
+        }
+    }
+
+    /**
+     * Dispatch one user-defined action. Equivalent to
+     * `peer.executor.execute(action, this.local_peer_id)` but exposed
+     * at the session level so callers don't need a reference to the
+     * executor or to know the local peer id.
+     *
+     * @param {SimAction} action_instance
+     */
+    send(action_instance) {
+        if (!this.#started) throw new Error("NetworkSession.send: call start() first");
+        if (!action_instance || action_instance.isSimAction !== true) {
+            throw new Error("NetworkSession.send: argument must be a SimAction instance");
+        }
+        this.#peer.executor.execute(action_instance, this.local_peer_id);
+    }
+
+    // ----------------------------------------------------------------
+    //  Accessors
+    // ----------------------------------------------------------------
+
+    /**
+     * @returns {ServerAuthoritativeServer|null}
+     */
+    get server() {
+        return this.#server;
+    }
+
+    /**
+     * @returns {ServerAuthoritativeClient|null}
+     */
+    get client() {
+        return this.#client;
+    }
+
+    /**
+     * @returns {NetworkPeer|null}
+     */
+    get peer() {
+        return this.#peer;
+    }
+
+    /**
+     * @returns {InterpolationLog|null}
+     */
+    get interpolation_log() {
+        return this.#interp_log;
+    }
+
+    /**
+     * @returns {AdaptiveRenderDelay}
+     */
+    get adaptive_render_delay() {
+        return this.#adaptive_render_delay;
+    }
+
+    /**
+     * @returns {TimeDilation}
+     */
+    get time_dilation() {
+        return this.#time_dilation;
+    }
+
+    /**
+     * Most recent locally-completed sim frame.
+     */
+    get current_frame() {
+        if (this.role === NetworkSessionRole.Host) return this.#server.current_sim_frame;
+        return this.#local_frame - 1;
+    }
+
+    // ----------------------------------------------------------------
+    //  Internal: identity observer (component-driven spawn/despawn)
+    // ----------------------------------------------------------------
+
+    /**
+     * Patch `NetworkIdentity` on attach: `owner_peer_id` defaults to
+     * this session's `local_peer_id` if unset; `network_id` is assigned
+     * by {@link NetworkSystem.link}, which fires on the same attach.
+     *
+     * Callers must not mutate either field afterwards — the slot table
+     * and replicator cache them.
+     *
+     */
+    #on_identity_attached(identity, entity_id) {
+        if (identity.owner_peer_id < 0) {
+            identity.owner_peer_id = this.local_peer_id;
+        }
+        if (identity.owner_peer_id !== this.local_peer_id) {
+            this.#remote_entities.add(entity_id);
+        }
+        // Per-entity event listener for net_mutate_component.
+        const listener = (payload) => this.#on_net_mutate_component(entity_id, payload);
+        this.world.addEntityEventListener(entity_id, "net_mutate_component", listener);
+        this.#event_listeners.set(entity_id, listener);
+    }
+
+    #on_identity_detached(_identity, entity_id) {
+        const listener = this.#event_listeners.get(entity_id);
+        if (listener !== undefined) {
+            this.world.removeEntityEventListener(entity_id, "net_mutate_component", listener);
+            this.#event_listeners.delete(entity_id);
+        }
+        this.#remote_entities.delete(entity_id);
+    }
+
+    /**
+     * Handler for `"net_mutate_component"` events. Translates the payload
+     * into a `ReplaceComponentAction` and dispatches via the executor.
+     *
+     * Payload:
+     *   - `{ component_type, new_state }` — recommended; engine captures
+     *     current bytes as prior, then applies `new_state` via the
+     *     replication adapter.
+     *   - `{ component_type }` — caller has already mutated live; prior
+     *     bytes equal post bytes (rewind for this mutation is a no-op).
+     *
+     */
+    #on_net_mutate_component(entity_id, payload) {
+        const { component_type, new_state } = payload || {};
+        if (!component_type) {
+            throw new Error("net_mutate_component: payload must include `component_type`");
+        }
+        const desc = this.#replicated.get(component_type);
+        if (desc === undefined) {
+            throw new Error(`net_mutate_component: ${component_type.typeName ?? component_type.name} is not replicated; call session.replicate() for it before mutating`);
+        }
+
+        const network_id = this.#peer.slot_table.network_for(entity_id);
+        if (network_id < 0) return; // not networked yet
+
+        const live = this.world.getComponent(entity_id, component_type);
+        if (live === undefined) return;
+
+        const adapter = this.binary_registry.getAdapter(component_type.typeName);
+
+        // Build the action with the new-state bytes pre-baked. The
+        // executor will then capture the current `live` as prior bytes
+        // before action.apply deserializes new bytes into `live`.
+        const action = this.#peer.action_registry.acquire(this.#ReplaceComponentAction);
+        action.network_id = network_id;
+        action.component_type_id = desc.interp_type_id;
+        action.payload_buf.position = 0;
+        if (new_state !== undefined && new_state !== null) {
+            adapter.serialize(action.payload_buf, new_state);
+        } else {
+            // No new_state: live IS the new state.
+            adapter.serialize(action.payload_buf, live);
+        }
+        action.payload_length = action.payload_buf.position;
+
+        try {
+            this.#peer.executor.execute(action, this.local_peer_id);
+        } finally {
+            this.#peer.action_registry.release(action);
+        }
+    }
+
+    /**
+     * Build the synthetic ReplaceComponentAction class.
+     * The factory captures `interp_type_id_to_class` and `binary_registry` by
+     * reference so the inner class methods can resolve type ids and
+     * adapters without reaching into the outer class's private fields
+     * (which `#`-private syntax would forbid from a different class).
+     */
+    #make_replace_component_action_class() {
+        const interp_type_id_to_class = this.#interp_type_id_to_class;
+        const binary_registry = this.binary_registry;
+        return class ReplaceComponentAction extends SimAction {
+            payload_length = 0;
+
+            constructor(network_id = 0, component_type_id = 0) {
+                super();
+                this.network_id = network_id;
+                this.component_type_id = component_type_id;
+                this.payload_buf = new BinaryBuffer();
+                this.payload_buf.setCapacity(SCRATCH_BUFFER_BYTES);
+            }
+
+            apply(world, executor) {
+                const local = executor.slot_table.entity_for(this.network_id);
+                if (local < 0) return;
+                const ComponentClass = interp_type_id_to_class[this.component_type_id];
+                if (ComponentClass === undefined) return;
+                const live = world.getComponent(local, ComponentClass);
+                if (live === undefined) return;
+                const adapter = binary_registry.getAdapter(ComponentClass.typeName);
+                if (adapter === undefined) return;
+                this.payload_buf.position = 0;
+                adapter.deserialize(this.payload_buf, live);
+            }
+
+            affected_components(callback, executor) {
+                const local = executor.slot_table.entity_for(this.network_id);
+                if (local < 0) return;
+                const ComponentClass = interp_type_id_to_class[this.component_type_id];
+                if (ComponentClass === undefined) return;
+                callback(local, ComponentClass);
+            }
+
+            serialize(buffer) {
+                buffer.writeUintVar(this.network_id);
+                buffer.writeUint8(this.component_type_id);
+                buffer.writeUint32(this.payload_length);
+                if (this.payload_length > 0) {
+                    buffer.writeBytes(this.payload_buf.raw_bytes, 0, this.payload_length);
+                }
+            }
+
+            deserialize(buffer) {
+                this.network_id = buffer.readUintVar();
+                this.component_type_id = buffer.readUint8();
+                this.payload_length = buffer.readUint32();
+                if (this.payload_buf.raw_bytes.length < this.payload_length) {
+                    this.payload_buf.setCapacity(this.payload_length);
+                }
+                if (this.payload_length > 0) {
+                    buffer.readBytes(this.payload_buf.raw_bytes, 0, this.payload_length);
+                }
+                this.payload_buf.position = 0;
+            }
+
+            reset() {
+                this.network_id = 0;
+                this.component_type_id = 0;
+                this.payload_length = 0;
+                this.payload_buf.position = 0;
+            }
+        };
+    }
+
+    // ----------------------------------------------------------------
+    //  Internal: per-step simulation
+    // ----------------------------------------------------------------
+
+    #simulate_one_step() {
+        if (this.role === NetworkSessionRole.Host) {
+            this.#server.tick(this.#local_frame);
+            this.#local_frame++;
+            return;
+        }
+        // Client. Dilated tick rate: each fixed step advances by
+        // `1 / dilation_factor` (capped at MAX_CLIENT_DILATED_TICKS_PER_STEP).
+        this.#local_frame_accum += 1.0 / this.#client.dilation_factor;
+        let inner = 0;
+        while (this.#local_frame_accum >= 1.0 && inner < MAX_CLIENT_DILATED_TICKS_PER_STEP) {
+            this.#local_frame_accum -= 1.0;
+            this.#client.tick(this.#local_frame);
+            this.#send_empty_ack_packet();
+            this.#local_frame++;
+            inner++;
+        }
+    }
+
+    /**
+     * Empty action-stream packet to advance the channel's seq/ack
+     * baseline on ticks with no outbound actions of our own.
+     */
+    #send_empty_ack_packet() {
+        for (const peer_id of this.#connected_peers) {
+            this.#peer.channel_for(peer_id).send(EMPTY_PAYLOAD, 0);
+        }
+    }
+
+    // ----------------------------------------------------------------
+    //  Internal: host-side tick completion (AUTH_STATE + dilation feedback)
+    // ----------------------------------------------------------------
+
+    /**
+     *
+     * @param {number} sim_frame
+     */
+    #on_host_tick_complete(sim_frame) {
+        // Initial-sync first, so receivers have a populated world before
+        // AUTH_STATE / action-stream packets land.
+        if (this.#pending_initial_sync.size > 0) {
+
+            for (const [peer_id, sends_remaining] of this.#pending_initial_sync) {
+
+                this.#send_initial_sync_to(peer_id, sim_frame);
+
+                if (sends_remaining <= 1) {
+                    this.#pending_initial_sync.delete(peer_id);
+                } else {
+                    this.#pending_initial_sync.set(peer_id, sends_remaining - 1);
+                }
+
+            }
+
+        }
+
+        // AUTH_STATE per owned entity, then time-dilation feedback, to
+        // every connected peer.
+        for (const peer_id of this.#connected_peers) {
+
+            for (const entity_id of this.#event_listeners.keys()) {
+
+                const identity = this.world.getComponent(entity_id, NetworkIdentity);
+
+                if (identity === undefined) {
+                    continue;
+                }
+                if (identity.owner_peer_id !== peer_id) {
+                    continue;
+                }
+
+                this.#send_auth_state_for_entity(peer_id, sim_frame, entity_id, identity);
+
+            }
+
+            this.#server.send_time_dilation_feedback(peer_id);
+        }
+    }
+
+
+    /**
+     * Emit a Snapshotter-format payload to a freshly-connected peer.
+     * Generates and stashes a UUID v1 session token on first send,
+     * which the receiver echoes back via RESUME_HELLO to authenticate
+     * later reconnects.
+     * @param {number} peer_id
+     * @param {number} sim_frame
+     */
+    #send_initial_sync_to(peer_id, sim_frame) {
+        let token = this.#peer_session_tokens.get(peer_id);
+
+        if (token === undefined) {
+            token = UUID.v1();
+            this.#peer_session_tokens.set(peer_id, token);
+        }
+
+        this.#peer.send_initial_sync(peer_id, token.data, sim_frame, (buf) => {
+            snapshotter_emit({
+                buffer: buf,
+                world: this.world,
+                slot_table: this.#peer.slot_table,
+                component_registry: this.#peer.component_registry,
+                entity_iter: (cb) => {
+                    for (const entity_id of this.#event_listeners.keys()) {
+                        cb(entity_id);
+                    }
+                },
+            });
+        });
+    }
+
+    /**
+     * Apply an inbound INITIAL_SYNC payload. Walks the wire format
+     * directly instead of using `snapshotter_apply` so we can:
+     *   - Handle re-sync (slot already allocated) without
+     *     `slot_table.allocate_at` throwing.
+     *   - Let `NetworkSystem.link` handle slot allocation on the
+     *     NetworkIdentity-attach side-effect (NetworkIdentity is always
+     *     first in the stream).
+     *
+     */
+    #apply_initial_sync(buffer, payload_end) {
+        const entity_count = buffer.readUintVar();
+        for (let i = 0; i < entity_count; i++) {
+            const network_id = buffer.readUintVar();
+            const component_count = buffer.readUint8();
+            let local_entity_id = this.#peer.slot_table.entity_for(network_id);
+            if (local_entity_id < 0) {
+                local_entity_id = this.world.createEntity();
+            }
+
+            for (let j = 0; j < component_count; j++) {
+                const type_id = buffer.readUint8();
+                const payload_len = buffer.readUint32();
+                const ComponentClass = this.#peer.component_registry.class_of(type_id);
+                const adapter = this.#peer.component_registry.adapter_for_id(type_id);
+                if (ComponentClass === undefined || adapter === undefined) {
+                    buffer.position += payload_len;
+                    continue;
+                }
+                const existing = this.world.getComponent(local_entity_id, ComponentClass);
+                if (existing === undefined) {
+                    const component = new ComponentClass();
+                    adapter.deserialize(buffer, component);
+                    this.world.addComponentToEntity(local_entity_id, component);
+                } else {
+                    adapter.deserialize(buffer, existing);
+                }
+            }
+
+            if (buffer.position > payload_end) {
+                throw new Error(`NetworkSession.#apply_initial_sync: read past payload_end at network_id ${network_id}`);
+            }
+        }
+    }
+
+    /**
+     *
+     * @param {number} peer_id
+     * @param {number} sim_frame
+     * @param {number} entity_id
+     * @param {NetworkIdentity} identity
+     */
+    #send_auth_state_for_entity(peer_id, sim_frame, entity_id, identity) {
+        const network_id = identity.network_id;
+
+        if (network_id < 0) {
+            // not initialized
+            return;
+        }
+
+        this.#peer.send_auth_state(peer_id, sim_frame, network_id, (buf) => {
+
+            // Concatenate all replicated components in #replicated order.
+            for (const [ComponentClass, desc] of this.#replicated) {
+
+                const live = this.world.getComponent(entity_id, ComponentClass);
+
+                if (live === undefined) {
+                    continue;
+                }
+
+                const adapter = this.binary_registry.getAdapter(ComponentClass.typeName);
+
+                adapter.serialize(buf, live);
+
+            }
+
+        });
+    }
+
+    // ----------------------------------------------------------------
+    //  Internal: host-side reconnect / grace / drop machinery
+    // ----------------------------------------------------------------
+
+    #wire_peer_transport_disconnect(peer_id, transport) {
+        if (!transport || !transport.onDisconnect) return;
+        const listener = (reason) => this.#on_peer_transport_disconnected(peer_id, reason);
+        transport.onDisconnect.add(listener);
+        this.#peer_transport_listeners.set(peer_id, { transport, listener });
+    }
+
+    #unwire_peer_transport_disconnect(peer_id) {
+        const entry = this.#peer_transport_listeners.get(peer_id);
+        if (entry === undefined) return;
+        try {
+            entry.transport.onDisconnect.remove(entry.listener);
+        } catch (_) { /* swallow */
+        }
+        this.#peer_transport_listeners.delete(peer_id);
+    }
+
+    /**
+     * Move a peer into the grace window after its transport reports a
+     * disconnect. The peer's channel + baseline are torn down (so a
+     * subsequent `connect()` on a fresh transport doesn't collide), but
+     * the session token, slot-table entries, and `last_acked` watermark
+     * are preserved for the grace window. On expiry, `#expire_grace_peers`
+     * promotes the peer to fully-dropped.
+     */
+    #on_peer_transport_disconnected(peer_id, reason) {
+        if (!this.#connected_peers.has(peer_id)) return;
+        const last_acked = this.#peer.baseline.last_acked(peer_id);
+        this.#server.disconnect_peer(peer_id);
+        this.#connected_peers.delete(peer_id);
+        this.#peer_inbound_mark.delete(peer_id);
+        this.#unwire_peer_transport_disconnect(peer_id);
+        this.#peer_grace_state.set(peer_id, {
+            deadline_ms: performance.now() + this.#server_resume_grace_ms,
+            last_acked,
+        });
+        this.onPeerLost.send2(peer_id, reason);
+    }
+
+    /**
+     * Validate a RESUME_HELLO and either welcome the peer back (restore
+     * baseline + send RESUME_ACCEPT) or reject with a reason code.
+     * Rejection schedules a fresh INITIAL_SYNC so the client falls
+     * through to Tier-3.
+     */
+    #on_resume_hello(transport_peer_id, claimed_peer_id, last_acked_frame, claimed_token_bytes) {
+        // Engine convention: the matchmaking layer routes the reconnecting
+        // transport to the same `peer_id` it had before. If `claimed_peer_id`
+        // disagrees with `transport_peer_id`, the matchmaker mis-routed —
+        // treat as collision and kick the connection cleanly. Symmetric
+        // with the TokenMismatch path below: we MUST NOT leave the rogue
+        // transport wired to the dispatcher (any subsequent packet would
+        // still be routed), and we MUST NOT add them to the connected
+        // set or queue an INITIAL_SYNC.
+        if (transport_peer_id !== claimed_peer_id) {
+            this.#peer.send_resume_reject(transport_peer_id, ResumeRejectReason.PeerIdCollision);
+            this.#peer.send_disconnect(transport_peer_id, 'peer_id_collision');
+            this.#server.disconnect_peer(transport_peer_id);
+            this.#unwire_peer_transport_disconnect(transport_peer_id);
+            // The transport may have been added to the live set in connect()
+            // (a fresh peer connects, then sends a mis-routed RESUME_HELLO).
+            // Drop it from BOTH iterated maps — otherwise the next host tick
+            // serializes AUTH_STATE / time-dilation to a now-disposed conn and
+            // throws "peer not connected", taking down the tick for all peers.
+            this.#connected_peers.delete(transport_peer_id);
+            this.#pending_initial_sync.delete(transport_peer_id);
+            this.#peer_inbound_mark.delete(transport_peer_id);
+            return;
+        }
+        const grace = this.#peer_grace_state.get(claimed_peer_id);
+        if (grace === undefined) {
+            // Either the peer is fully unknown OR they're already
+            // connected (their previous transport never dropped).
+            // Either way, no resume record to validate against.
+            this.#peer.send_resume_reject(transport_peer_id, ResumeRejectReason.UnknownPeer);
+            // Treat as a fresh peer; schedule INITIAL_SYNC.
+            this.#pending_initial_sync.set(transport_peer_id, 2);
+            this.#connected_peers.add(transport_peer_id);
+            return;
+        }
+        const expected_token = this.#peer_session_tokens.get(claimed_peer_id);
+        if (expected_token === undefined) {
+            this.#peer.send_resume_reject(transport_peer_id, ResumeRejectReason.UnknownPeer);
+            this.#peer_grace_state.delete(claimed_peer_id);
+            this.#pending_initial_sync.set(transport_peer_id, 2);
+            this.#connected_peers.add(transport_peer_id);
+            return;
+        }
+        const claimed = new UUID();
+        claimed.data = claimed_token_bytes;
+        if (!claimed.equals(expected_token)) {
+            // Hard reject: a wrong-token attempt MUST NOT take over the
+            // legitimate peer's grace state (would let an attacker
+            // pre-empt the real owner's reconnect window) and MUST NOT
+            // be fresh-treated either (would expose the world via
+            // INITIAL_SYNC). Kick the connection; legitimate-but-
+            // corrupted-token clients fall to permanent-lost and need
+            // a new peer_id from the matchmaking layer.
+            this.#peer.send_resume_reject(transport_peer_id, ResumeRejectReason.TokenMismatch);
+            this.#peer.send_disconnect(transport_peer_id, 'token_mismatch');
+            this.#server.disconnect_peer(transport_peer_id);
+            this.#unwire_peer_transport_disconnect(transport_peer_id);
+            // Same cleanup as the collision branch above: if this transport was
+            // a fresh peer added to the live set, drop it from both iterated
+            // maps so the next host tick doesn't address a disposed conn.
+            this.#connected_peers.delete(transport_peer_id);
+            this.#pending_initial_sync.delete(transport_peer_id);
+            this.#peer_inbound_mark.delete(transport_peer_id);
+            return;
+        }
+        // Ring-floor gate. The client asks to resume from `last_acked_frame + 1`,
+        // but the action-log ring only still holds frames back to
+        // `current_sim_frame - frame_capacity + 1`. If the requested frame
+        // predates that floor, the frames needed to back-fill the gap have aged
+        // out — `pack_for_peer`'s has_frame guard would silently skip them and
+        // the client would enter `connected` missing in-scope mutations (a
+        // "successful" resume that runs visibly desynced). Reject so the client
+        // falls through to a full INITIAL_SYNC re-sync instead. Grace is
+        // typically far longer than the ring, so this is the routine case for
+        // any reconnect that took more than ~`frame_capacity` ticks.
+        const ring_floor = this.#server.current_sim_frame - this.frame_capacity + 1;
+        if (last_acked_frame + 1 < ring_floor) {
+            this.#peer.send_resume_reject(transport_peer_id, ResumeRejectReason.StaleFrame);
+            this.#peer_grace_state.delete(claimed_peer_id);
+            this.#pending_initial_sync.set(transport_peer_id, 2);
+            this.#connected_peers.add(transport_peer_id);
+            return;
+        }
+
+        // Valid resume. Restore the action-stream baseline so the
+        // replicator packs from `last_acked + 1`, then accept.
+        this.#peer.baseline.set_acked(claimed_peer_id, last_acked_frame);
+        this.#peer_grace_state.delete(claimed_peer_id);
+        this.#connected_peers.add(transport_peer_id);
+        this.#peer.send_resume_accept(transport_peer_id);
+    }
+
+    /**
+     * Walk the grace map and promote any peer whose deadline has
+     * passed to fully-dropped (fires `onPeerPermanentlyDropped`).
+     * Called from `tick()`.
+     */
+    #expire_grace_peers(now_ms) {
+        if (this.#peer_grace_state.size === 0) return;
+        for (const [peer_id, state] of this.#peer_grace_state) {
+            if (state.deadline_ms <= now_ms) {
+                this.#peer_grace_state.delete(peer_id);
+                this.#peer_session_tokens.delete(peer_id);
+                this.onPeerPermanentlyDropped.send2(peer_id, 'grace_expired');
+            }
+        }
+    }
+
+    /**
+     * Reap any connected peer whose inbound-packet count has not advanced for
+     * longer than `connection_timeout_ms`. Host-side peers go into the grace
+     * window (the same path a transport disconnect takes); the client routes a
+     * silent server into the reconnect ladder. Connectionless transports never
+     * emit a disconnect of their own, so without this a vanished peer would be
+     * pinned forever (host) or never noticed (client). The per-tick keepalive
+     * traffic the facade sends both directions keeps a live connection well
+     * clear of the budget. Called from `tick()` only when the budget is > 0.
+     * @private
+     */
+    #reap_silent_peers() {
+        if (this.role === NetworkSessionRole.Host) {
+            // Collect first — reaping mutates #connected_peers mid-iteration.
+            let to_reap = null;
+            for (const peer_id of this.#connected_peers) {
+                if (this.#peer_is_silent(peer_id)) (to_reap ??= []).push(peer_id);
+            }
+            if (to_reap !== null) {
+                for (let i = 0; i < to_reap.length; i++) {
+                    this.#on_peer_transport_disconnected(to_reap[i], 'timeout');
+                }
+            }
+        } else if (this.#reconnect_state === ReconnectState.Connected && this.#remote_peer_id >= 0) {
+            // Only when actively connected — Reconnecting/Resyncing have their
+            // own timers in #tick_reconnect.
+            if (this.#peer_is_silent(this.#remote_peer_id)) {
+                this.#on_client_transport_disconnected('timeout');
+            }
+        }
+    }
+
+    /**
+     * Whether `peer_id` has produced no inbound packet within the timeout
+     * budget. Maintains the per-peer mark as a side effect: resets the silence
+     * window whenever the peer's inbound count advances. A freshly-seen peer is
+     * stamped at the current clock and reported live, so it always gets a full
+     * budget before it can be reaped.
+     * @private
+     */
+    #peer_is_silent(peer_id) {
+        const count = this.#peer.inbound_count(peer_id);
+        const mark = this.#peer_inbound_mark.get(peer_id);
+        if (mark === undefined) {
+            this.#peer_inbound_mark.set(peer_id, { count, since_ms: this.#liveness_clock_ms });
+            return false;
+        }
+        if (count !== mark.count) {
+            mark.count = count;
+            mark.since_ms = this.#liveness_clock_ms;
+            return false;
+        }
+        return this.#liveness_clock_ms - mark.since_ms >= this.#connection_timeout_ms;
+    }
+
+    // ----------------------------------------------------------------
+    //  Internal: client-side reconnect state machine
+    // ----------------------------------------------------------------
+
+    #wire_client_transport_disconnect(transport) {
+        if (!transport || !transport.onDisconnect) return;
+        if (this.#current_transport_listener !== null && this.#current_transport !== null) {
+            try {
+                this.#current_transport.onDisconnect.remove(this.#current_transport_listener);
+            } catch (_) { /* swallow */
+            }
+        }
+        const listener = (reason) => this.#on_client_transport_disconnected(reason);
+        transport.onDisconnect.add(listener);
+        this.#current_transport_listener = listener;
+    }
+
+    #on_client_transport_disconnected(reason) {
+        if (this.#reconnect_state === ReconnectState.Lost) return;
+        // Tear down the dead peer/channel binding so a fresh transport
+        // can be wired via `connect()`. The InterpolationLog,
+        // session_token, predicted-action ledger, and live world all
+        // survive — that's what we need to claim continuity on resume.
+        if (this.#remote_peer_id >= 0) {
+            try {
+                this.#peer.disconnect_peer(this.#remote_peer_id);
+            } catch (_) { /* swallow */
+            }
+            // Stop treating this peer as a live send target. The channel is
+            // gone, but `#remote_peer_id` is deliberately kept so the reconnect
+            // ladder can re-`connect()` to the same id. Without this delete,
+            // `#send_empty_ack_packet` (driven every tick) dereferences the
+            // now-undefined channel and throws — which would crash the very
+            // tick loop that drives the reconnect ladder.
+            this.#connected_peers.delete(this.#remote_peer_id);
+            this.#peer_inbound_mark.delete(this.#remote_peer_id);
+        }
+        this.#current_transport = null;
+        this.#current_transport_listener = null;
+        if (!this.#reconnect_policy.enabled) {
+            this.#permanently_lose_connection(reason || 'transport_disconnect');
+            return;
+        }
+        this.#reconnect_state = ReconnectState.Reconnecting;
+        this.#reconnect_attempt = 0;
+        this.#reconnect_elapsed_ms = 0;
+        this.#reconnect_next_delay_ms = this.#reconnect_policy.base_delay_ms;
+        this.#reconnect_timer_remaining_ms = this.#reconnect_next_delay_ms;
+        this.onConnectionLost.send1(reason || 'transport_disconnect');
+    }
+
+    /**
+     * Per-tick advance for the client reconnect timer. When the timer
+     * elapses we rebuild the transport via `transport_factory` and
+     * call `connect()` on it; with a cached `session_token`, `connect`
+     * sends RESUME_HELLO. The server replies with RESUME_ACCEPT
+     * (→ Connected) or RESUME_REJECT (→ Resyncing, INITIAL_SYNC
+     * pending) or nothing within the next back-off interval (→ retry).
+     */
+    #tick_reconnect(dt_ms) {
+        // Resyncing has its own deadline: after RESUME_REJECT we expect
+        // the host to ship a fresh INITIAL_SYNC. If it never arrives
+        // (host crashed, network silently broke), fall to Lost so the
+        // application sees the failure instead of hanging forever.
+        if (this.#reconnect_state === ReconnectState.Resyncing) {
+            this.#reconnect_elapsed_ms += dt_ms;
+            if (this.#reconnect_elapsed_ms >= this.#reconnect_policy.total_timeout_ms) {
+                this.#permanently_lose_connection('resync_timeout');
+            }
+            return;
+        }
+        if (this.#reconnect_state !== ReconnectState.Reconnecting) return;
+        this.#reconnect_elapsed_ms += dt_ms;
+        if (this.#reconnect_elapsed_ms >= this.#reconnect_policy.total_timeout_ms) {
+            this.#permanently_lose_connection('reconnect_timeout');
+            return;
+        }
+        this.#reconnect_timer_remaining_ms -= dt_ms;
+        if (this.#reconnect_timer_remaining_ms > 0) return;
+
+        // Time to attempt.
+        this.#reconnect_attempt++;
+        if (this.#reconnect_attempt > this.#reconnect_policy.max_attempts) {
+            this.#permanently_lose_connection('reconnect_attempts_exhausted');
+            return;
+        }
+        this.onReconnectAttempt.send1(this.#reconnect_attempt);
+
+        if (this.#transport_factory === null) {
+            // No factory: caller must drive reconnects themselves. We
+            // remain in Reconnecting until they call connect() with a
+            // new transport, or until total_timeout_ms expires.
+            this.#reconnect_timer_remaining_ms = this.#next_backoff_delay();
+            return;
+        }
+        let new_transport;
+        try {
+            new_transport = this.#transport_factory();
+        } catch (e) {
+            console.warn('NetworkSession: transport_factory threw', e);
+            this.#reconnect_timer_remaining_ms = this.#next_backoff_delay();
+            return;
+        }
+        try {
+            this.connect(this.#remote_peer_id, new_transport);
+        } catch (e) {
+            console.warn('NetworkSession: connect() threw during reconnect', e);
+            this.#reconnect_timer_remaining_ms = this.#next_backoff_delay();
+            return;
+        }
+        // Wait the back-off interval before retrying again (if RESUME_ACCEPT
+        // never arrives in time).
+        this.#reconnect_timer_remaining_ms = this.#next_backoff_delay();
+    }
+
+    #next_backoff_delay() {
+        const next = this.#reconnect_next_delay_ms * this.#reconnect_policy.exponential_factor;
+        this.#reconnect_next_delay_ms = Math.min(next, this.#reconnect_policy.max_delay_ms);
+        return this.#reconnect_next_delay_ms;
+    }
+
+    #enter_connected() {
+        this.#reconnect_state = ReconnectState.Connected;
+        this.#reconnect_attempt = 0;
+        this.#reconnect_elapsed_ms = 0;
+        // Reset the exponential back-off so a subsequent disconnect starts
+        // its retry ladder from base_delay_ms — without this, the next drop
+        // would inherit the last cycle's (potentially max_delay_ms) delay.
+        this.#reconnect_next_delay_ms = this.#reconnect_policy.base_delay_ms;
+    }
+
+    #permanently_lose_connection(reason) {
+        if (this.#reconnect_state === ReconnectState.Lost) return;
+        this.#reconnect_state = ReconnectState.Lost;
+        this.onConnectionPermanentlyLost.send1(reason);
+    }
+
+    // ----------------------------------------------------------------
+    //  Internal: client predict-reconcile wiring
+    // ----------------------------------------------------------------
+
+    #wire_client_predict_reconcile() {
+        // Rewind doesn't go through executor.execute, so the
+        // before_execute normalize hook misses it. Catch it here.
+        this.#client.onBeforeReconcile.add(() => this.normalize_if_dirty());
+
+        // Predict: run the sampler, execute each action, record its
+        // bytes so the replay path can re-execute without re-sampling.
+        this.#client.onPredict.add((frame, _input_writer) => {
+            if (this.#input_sampler === null) return;
+            const actions = this.#input_sampler(frame);
+            if (!actions) return;
+            const recorded = [];
+            for (const action of actions) {
+                if (!action || action.isSimAction !== true) continue;
+                const type_id = action.constructor.type_id;
+                const scratch = this.#scratch_send_buf;
+                scratch.position = 0;
+                action.serialize(scratch);
+                const bytes = scratch.raw_bytes.slice(0, scratch.position);
+                recorded.push({ type_id, bytes });
+                this.#client.executor.execute(action, this.local_peer_id);
+            }
+            this.#sampled_actions_per_frame.set(frame, recorded);
+            this.#trim_sampled_action_ledger();
+        });
+
+        // Replay: re-execute recorded actions from the ledger. Sampler is
+        // NOT called again — live input has moved on.
+        this.#client.onReplay.add((frame, _input_reader) => {
+            const recorded = this.#sampled_actions_per_frame.get(frame);
+            if (!recorded) return;
+            for (const { type_id, bytes } of recorded) {
+                const klass = this.#peer.action_registry.klass_for(type_id);
+                if (klass === undefined) continue;
+                const action = this.#peer.action_registry.acquire(klass);
+                const scratch = this.#scratch_interp_buf;
+                scratch.position = 0;
+                scratch.writeBytes(bytes, 0, bytes.length);
+                scratch.position = 0;
+                action.deserialize(scratch);
+                try {
+                    this.#client.executor.execute(action, this.local_peer_id);
+                } finally {
+                    this.#peer.action_registry.release(action);
+                }
+            }
+        });
+
+        // Apply auth state: deserialize concatenated replicated-component
+        // bytes into the live entity. Mirrors the host's serialize order.
+        this.#client.onApplyAuthState.add((_server_frame, network_id, buffer) => {
+            const local = this.#client.slot_table.entity_for(network_id);
+            if (local < 0) return;
+            for (const [ComponentClass] of this.#replicated) {
+                const live = this.world.getComponent(local, ComponentClass);
+                if (live === undefined) continue;
+                const adapter = this.binary_registry.getAdapter(ComponentClass.typeName);
+                adapter.deserialize(buffer, live);
+            }
+        });
+    }
+
+    #trim_sampled_action_ledger() {
+        const action_log = this.#peer.action_log;
+        if (action_log === undefined) return;
+        const oldest_keep = Math.max(0, this.#local_frame - action_log.frame_capacity);
+        for (const f of this.#sampled_actions_per_frame.keys()) {
+            if (f < oldest_keep) this.#sampled_actions_per_frame.delete(f);
+        }
+    }
+
+    // ----------------------------------------------------------------
+    //  Internal: interpolation log + render-time sampling
+    // ----------------------------------------------------------------
+
+    /**
+     * Record post-apply state for every remote-owned entity into the
+     * interpolation log. Locally-owned entities are predicted, not
+     * interpolated, so they're skipped.
+     *
+     * Doesn't fire on the host — the replicator's deferral path doesn't
+     * emit `onFrameApplied`, so the host gets no recording naturally.
+     */
+    #on_frame_applied(_peer_id, frame_number) {
+        this.#interp_log.begin_tick(frame_number);
+        for (const entity_id of this.#remote_entities) {
+            const identity = this.world.getComponent(entity_id, NetworkIdentity);
+            if (identity === undefined || identity.network_id < 0) continue;
+            for (const [ComponentClass, desc] of this.#replicated) {
+                if (desc.interp === null) continue;
+                const live = this.world.getComponent(entity_id, ComponentClass);
+                if (live === undefined) continue;
+                const adapter = this.binary_registry.getAdapter(ComponentClass.typeName);
+                const rec_buf = this.#interp_log.begin_record(identity.network_id, desc.interp_type_id);
+                adapter.serialize(rec_buf, live);
+                this.#interp_log.end_record();
+            }
+        }
+        this.#interp_log.end_tick();
+
+        if (frame_number > this.#latest_received_frame) {
+            this.#adaptive_render_delay.record_arrival(performance.now(), frame_number);
+            this.#latest_received_frame = frame_number;
+        }
+    }
+
+    /**
+     * Advance the smooth_render_frame state machine and write
+     * interpolated bytes into each remote-owned entity's live
+     * components. Sets `render_dirty` if anything was written.
+     *
+     * Host early-returns naturally (no `#latest_received_frame`
+     * recorded — deferred-apply path doesn't fire `onFrameApplied`).
+     */
+    #render_interpolated_entities() {
+        if (this.#latest_received_frame < 0) return;
+        if (this.#remote_entities.size === 0) return;
+
+        const now_ms = performance.now();
+        const render_delay_frames = this.#adaptive_render_delay.delay_ms() / this.tick_period_ms;
+        const target = this.#latest_received_frame - render_delay_frames;
+
+        if (this.#smooth_render_frame < 0) {
+            this.#smooth_render_frame = target < 0 ? 0 : target;
+            this.#smooth_last_wall_ms = now_ms;
+        } else {
+            const dt_ms = now_ms - this.#smooth_last_wall_ms;
+            this.#smooth_last_wall_ms = now_ms;
+            this.#smooth_render_frame += dt_ms / this.tick_period_ms;
+            const alpha = 1 - Math.exp(-PULL_PER_MS * dt_ms);
+            this.#smooth_render_frame += (target - this.#smooth_render_frame) * alpha;
+        }
+        if (this.#smooth_render_frame > this.#latest_received_frame) {
+            this.#smooth_render_frame = this.#latest_received_frame;
+        }
+        if (this.#smooth_render_frame < 0) this.#smooth_render_frame = 0;
+
+        const tick_a = Math.floor(this.#smooth_render_frame);
+        const tick_b = tick_a + 1;
+        const t = this.#smooth_render_frame - tick_a;
+
+        const scratch = this.#scratch_interp_buf;
+        let wrote_anything = false;
+        for (const entity_id of this.#remote_entities) {
+            const identity = this.world.getComponent(entity_id, NetworkIdentity);
+            if (identity === undefined || identity.network_id < 0) continue;
+            for (const [ComponentClass, desc] of this.#replicated) {
+                if (desc.interp === null) continue; // snap mode
+                const live = this.world.getComponent(entity_id, ComponentClass);
+                if (live === undefined) continue;
+                scratch.position = 0;
+                const ok = this.#interp_log.interpolate(
+                    scratch, identity.network_id, desc.interp_type_id,
+                    tick_a, tick_b, t, desc.interp,
+                );
+                if (!ok) continue;
+                scratch.position = 0;
+                const adapter = this.binary_registry.getAdapter(ComponentClass.typeName);
+                adapter.deserialize(scratch, live);
+                wrote_anything = true;
+            }
+        }
+        if (wrote_anything) this.render_dirty = true;
+    }
+
+    // ----------------------------------------------------------------
+    //  Utility
+    // ----------------------------------------------------------------
+
+    #assert_not_started(method_name) {
+        if (this.#started) {
+            throw new Error(`NetworkSession.${method_name}: must be called before start()`);
+        }
+    }
+}