@series-inc/rundot-syncplay 5.23.0-beta.7

package/dist/networked-client.js

@@ -0,0 +1,688 @@
+import { canonicalStringify, cloneCanonical, defaultChecksum } from './canonical.js';
+import { SyncplayError } from './errors.js';
+import { createDeterministicLocalAuthoritySnapshotChunkEnvelope, createDeterministicLocalAuthoritySnapshotCompleteEnvelope, createDeterministicLocalAuthoritySnapshotOfferEnvelope, decodeDeterministicLocalAuthorityWireEnvelope, } from './local-authority-wire.js';
+import { base64ToBytes, bytesToBase64, createSnapshotTransferCollector, createSnapshotTransferFromBytes, decodeDeterministicStateSnapshot, deterministicRoomDescriptorHash, encodeDeterministicStateSnapshot, } from './session-snapshot.js';
+import { decodeDeterministicSessionMessage, encodeDeterministicSessionMessage } from './session-wire.js';
+const DEFAULT_MSG_TYPE = 'rdm';
+const DEFAULT_MAX_PREDICTION = 8;
+const DEFAULT_CHECKSUM_CADENCE_TICKS = 120;
+const DEFAULT_PING_INTERVAL_MS = 1000;
+const DEFAULT_TARGET_LEAD_TICKS = 2;
+const DEFAULT_MIN_TIMESCALE = 0.9;
+const DEFAULT_MAX_TIMESCALE = 1.1;
+const DEFAULT_CORRECTION_PER_TICK = 0.02;
+const DEFAULT_MAX_STEPS_PER_PUMP = 4;
+/** Frame-advantage error inside this band leaves the timescale at 1 (no hunting on jitter). */
+const TIMESCALE_DEADBAND_TICKS = 1;
+/** RTT smoothing factor (EWMA); ~4 samples to converge. */
+const RTT_EWMA_ALPHA = 0.25;
+/** Consecutive agreeing samples before an adaptive input-delay change applies. */
+const INPUT_DELAY_HYSTERESIS_SAMPLES = 3;
+/**
+ * Authority-clock observations retained for the estimate. Confirmed-input
+ * broadcasts feed one per authority tick, so a transient over-estimate
+ * (RTT spike, delivery burst) ages out in well under a second.
+ */
+const AUTHORITY_EPOCH_WINDOW = 16;
+/** Reported ticks kept for donor eligibility (a donor only offers ticks it reported). */
+const REPORTED_TICKS_RETAINED = 64;
+/** Donor upload pacing: transfer envelopes flushed per pump() call. */
+const TRANSFER_SENDS_PER_PUMP = 2;
+export function createNetworkedSyncplayClient(options) {
+    const sessionMsgType = options.sessionMsgType ?? DEFAULT_MSG_TYPE;
+    const maxPredictionTicks = options.maxPredictionTicks ?? DEFAULT_MAX_PREDICTION;
+    const checksumCadenceTicks = options.checksumCadenceTicks ?? DEFAULT_CHECKSUM_CADENCE_TICKS;
+    const pingIntervalMs = options.pacing?.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
+    const targetLeadTicks = options.pacing?.targetLeadTicks ?? DEFAULT_TARGET_LEAD_TICKS;
+    const minTimescale = options.pacing?.minTimescale ?? DEFAULT_MIN_TIMESCALE;
+    const maxTimescale = options.pacing?.maxTimescale ?? DEFAULT_MAX_TIMESCALE;
+    const correctionPerTick = options.pacing?.correctionPerTick ?? DEFAULT_CORRECTION_PER_TICK;
+    const maxStepsPerPump = options.pacing?.maxStepsPerPump ?? DEFAULT_MAX_STEPS_PER_PUMP;
+    const inputDelayMinTicks = options.inputDelay?.minTicks ?? 0;
+    const inputDelayMaxTicks = Math.max(options.inputDelay?.maxTicks ?? inputDelayMinTicks, inputDelayMinTicks);
+    const wallClock = options.now ?? (() => Date.now());
+    let session;
+    let slot = -1;
+    let role = 'player';
+    let seed = 0;
+    let playerCount = 0;
+    let predictedThrough = 0;
+    let appliedThrough = -1;
+    let rollbacks = 0;
+    let maxRollbackDepth = 0;
+    // ── G1/G2 pacing state (only advanced by pumpPaced; inert under raw pump) ──
+    let tickRateHz = 0;
+    let frameMs = 0;
+    let pingNonce = 0;
+    const pendingPings = new Map();
+    let lastPingSentMs;
+    let rttMs = -1;
+    // Windowed authority-clock observations, stored as epochs (the wall time at
+    // which authority tick 0 would have happened, assuming nominal rate). Using
+    // the window MIN epoch (= max tick estimate) keeps jitter robustness, while
+    // the bounded window lets the estimate RE-BASE DOWN: a slow-ticking server
+    // or a one-off RTT spike ages out of the window instead of inflating the
+    // estimate forever (which pinned clients at the prediction cap).
+    const authorityEpochsMs = [];
+    let timescale = 1;
+    let pacingAccumulatorMs = 0;
+    let lastPumpPacedMs;
+    // Own-input scheduling (G2): the next tick to sample+send our input for.
+    // With delay D, predicting tick T schedules through T+D; the cursor is
+    // monotone, so a mid-session delay change can never gap or rebind a tick
+    // that was already sent.
+    let inputDelayTicks = inputDelayMinTicks;
+    let ownScheduleCursor = 0;
+    let pendingDelayCandidate = inputDelayMinTicks;
+    let pendingDelayAgreement = 0;
+    const timeline = [];
+    const ownInputs = new Map();
+    const confirmed = new Map();
+    let lastConfirmedBySlot = [];
+    // M5.5 snapshot late-join state: identities from session-start (descriptor)
+    // and the session config (schema), the donor upload queue, and the joiner's
+    // transfer collector.
+    let descriptorHash = '';
+    let schemaHash = '';
+    const reportedTicks = [];
+    let lastAutoReportedTick = -1;
+    let transferCollector = createSnapshotTransferCollector();
+    const outgoingTransferQueue = [];
+    let donorTransferCounter = 0;
+    let readyResolve;
+    const readyPromise = new Promise((resolve) => {
+        readyResolve = resolve;
+    });
+    options.transport.onMessage((text) => {
+        const decoded = decodeDeterministicSessionMessage(text);
+        if (!decoded.ok) {
+            // The other frozen wire family (snapshot negotiation) rides the same
+            // msgType; it carries schemaVersion where session messages carry v, so
+            // a session-decode failure is the expected path for it. Both decoders
+            // fail closed.
+            handleSnapshotWireMessage(text);
+            return;
+        }
+        const message = decoded.message;
+        if (message.kind === 'session-start') {
+            // A REPEAT session-start means the authority restarted (M6.5 crash
+            // recovery re-greets every seated player): this client's timeline forked
+            // past the restored frontier, so everything resets — the snapshot+tail
+            // that follow re-hydrate it exactly like a fresh late joiner.
+            slot = message.slot;
+            role = message.role;
+            seed = message.seed;
+            playerCount = message.playerCount;
+            lastConfirmedBySlot = Array.from({ length: playerCount }, () => null);
+            appliedThrough = -1;
+            predictedThrough = 0;
+            timeline.length = 0;
+            ownInputs.clear();
+            confirmed.clear();
+            reportedTicks.length = 0;
+            lastAutoReportedTick = -1;
+            transferCollector = createSnapshotTransferCollector();
+            outgoingTransferQueue.length = 0;
+            tickRateHz = message.tickRateHz;
+            frameMs = tickRateHz > 0 ? 1000 / tickRateHz : 0;
+            ownScheduleCursor = 0;
+            pacingAccumulatorMs = 0;
+            // A re-greet resets the sim; pacing estimates must not survive it either
+            // (fresh observations arrive with the very next confirmed-input).
+            authorityEpochsMs.length = 0;
+            pendingPings.clear();
+            timescale = 1;
+            session = options.createSession({ seed, playerCount });
+            descriptorHash = deterministicRoomDescriptorHash({
+                seed: message.seed,
+                playerCount: message.playerCount,
+                tickRateHz: message.tickRateHz,
+                hardToleranceTicks: message.hardToleranceTicks,
+            });
+            schemaHash = defaultChecksum({ kind: 'rdm-schema-identity', ...session.schemaIdentity });
+            readyResolve?.();
+        }
+        else if (message.kind === 'confirmed-input') {
+            observeAuthorityTick(message.authorityTick, wallClock());
+            applyConfirmedFrames(message.frames);
+        }
+        else if (message.kind === 'time-sync-pong') {
+            handleTimeSyncPong(message.nonce, message.authorityTick);
+        }
+    });
+    // ── G1: authority-clock estimation + drift-corrected timescale ──
+    function handleTimeSyncPong(nonce, authorityTick) {
+        const sentAtMs = pendingPings.get(nonce);
+        if (sentAtMs === undefined) {
+            return;
+        }
+        pendingPings.delete(nonce);
+        const nowMs = wallClock();
+        const sampleRttMs = Math.max(0, nowMs - sentAtMs);
+        rttMs = rttMs < 0 ? sampleRttMs : rttMs + RTT_EWMA_ALPHA * (sampleRttMs - rttMs);
+        // observeAuthorityTick adds the one-way delay itself — pass the raw tick.
+        observeAuthorityTick(authorityTick, nowMs);
+        maybeAdaptInputDelay();
+    }
+    function halfRttTicks() {
+        if (rttMs < 0 || frameMs <= 0) {
+            return 0;
+        }
+        return rttMs / 2 / frameMs;
+    }
+    /**
+     * Fold a new authority-tick observation into the windowed estimator.
+     * Confirmed-input broadcasts and pongs both feed it. Each observation is
+     * normalized to an epoch; the estimate extrapolates from the window-min
+     * epoch (jitter-robust max bias) while old observations age out, so the
+     * estimate tracks a server whose real tick period drifts from nominal and
+     * recovers from transient RTT inflation instead of overestimating forever.
+     */
+    function observeAuthorityTick(tick, atMs) {
+        if (frameMs <= 0) {
+            return;
+        }
+        const observed = tick + halfRttTicks();
+        authorityEpochsMs.push(atMs - observed * frameMs);
+        if (authorityEpochsMs.length > AUTHORITY_EPOCH_WINDOW) {
+            authorityEpochsMs.shift();
+        }
+    }
+    function estimatedAuthorityTick(nowMs) {
+        if (authorityEpochsMs.length === 0 || frameMs <= 0) {
+            return undefined;
+        }
+        return (nowMs - Math.min(...authorityEpochsMs)) / frameMs;
+    }
+    /**
+     * The pacing controller (G1). Input for tick T+delay is sent while predicting
+     * T and needs one-way latency to arrive, so the client wants to run ahead of
+     * the authority by ~(halfRTT - inputDelay + safety margin) ticks. Error
+     * outside a ±1-tick deadband nudges the timescale, clamped to ±10% —
+     * micro-sleep when ahead, step-faster when behind, never a visible snap.
+     */
+    function updateTimescale(nowMs) {
+        const authorityNow = estimatedAuthorityTick(nowMs);
+        if (authorityNow === undefined) {
+            timescale = 1;
+            return;
+        }
+        const frameAdvantage = predictedThrough - authorityNow;
+        const targetAdvantage = Math.max(targetLeadTicks, halfRttTicks() - inputDelayTicks + targetLeadTicks);
+        const error = frameAdvantage - targetAdvantage;
+        if (Math.abs(error) <= TIMESCALE_DEADBAND_TICKS) {
+            timescale = 1;
+            return;
+        }
+        timescale = clamp(1 - error * correctionPerTick, minTimescale, maxTimescale);
+    }
+    function maybeSendPing(nowMs) {
+        if (lastPingSentMs !== undefined && nowMs - lastPingSentMs < pingIntervalMs) {
+            return;
+        }
+        lastPingSentMs = nowMs;
+        pingNonce += 1;
+        pendingPings.set(pingNonce, nowMs);
+        // A lost pong must not leak: keep only the most recent few outstanding.
+        if (pendingPings.size > 8) {
+            const oldest = pendingPings.keys().next().value;
+            if (oldest !== undefined)
+                pendingPings.delete(oldest);
+        }
+        options.transport.send(encodeDeterministicSessionMessage({ kind: 'time-sync-ping', clientSendTick: predictedThrough, nonce: pingNonce }));
+    }
+    // ── G2: ping-adaptive own-input delay ──
+    function maybeAdaptInputDelay() {
+        if (inputDelayMaxTicks <= inputDelayMinTicks) {
+            return;
+        }
+        const desired = clamp(Math.ceil(halfRttTicks()), inputDelayMinTicks, inputDelayMaxTicks);
+        if (desired === inputDelayTicks) {
+            pendingDelayAgreement = 0;
+            return;
+        }
+        if (desired === pendingDelayCandidate) {
+            pendingDelayAgreement += 1;
+        }
+        else {
+            pendingDelayCandidate = desired;
+            pendingDelayAgreement = 1;
+        }
+        if (pendingDelayAgreement >= INPUT_DELAY_HYSTERESIS_SAMPLES) {
+            inputDelayTicks = pendingDelayCandidate;
+            pendingDelayAgreement = 0;
+        }
+    }
+    function clamp(value, min, max) {
+        return Math.min(max, Math.max(min, value));
+    }
+    /**
+     * Decode a wire input fail-closed (§2.4.5 hostile-input hardening): the
+     * authority is game-agnostic and relays opaque payloads, so a hostile peer
+     * can put anything into a CONFIRMED frame. A payload the game's decoder
+     * throws on becomes the canonical neutral instead of crashing every honest
+     * client — deterministically, since every client throws on the same bytes.
+     * If even the neutral decode throws, that is a game bug: fail loud.
+     */
+    function decodeInputSafe(encoded) {
+        try {
+            return options.decodeInput(encoded);
+        }
+        catch {
+            return options.decodeInput(null);
+        }
+    }
+    function inputForSlot(targetSlot, tick) {
+        const conf = confirmed.get(tick);
+        if (conf !== undefined) {
+            return conf[targetSlot];
+        }
+        if (targetSlot === slot) {
+            // Scheduled by the cursor (possibly delay-shifted). A tick with no
+            // schedule entry (e.g. the first `inputDelayTicks` ticks) plays the
+            // canonical neutral — the same substitute the authority would use.
+            return ownInputs.get(tick) ?? null;
+        }
+        return lastConfirmedBySlot[targetSlot];
+    }
+    /**
+     * Sample, bind and send this client's input for every unscheduled tick up to
+     * `targetTick`. The cursor is monotone: a tick is sampled and sent exactly
+     * once, so adaptive delay changes shift only FUTURE bindings. Spectators
+     * (G11) hold no slot and never sample or send input.
+     */
+    function scheduleOwnInputsThrough(targetTick) {
+        if (role === 'spectator') {
+            return;
+        }
+        while (ownScheduleCursor <= targetTick) {
+            const tick = ownScheduleCursor;
+            let own = ownInputs.get(tick);
+            if (own === undefined) {
+                own = options.encodeInput(options.localInputForTick(slot, tick));
+                ownInputs.set(tick, own);
+            }
+            sendInput(tick, own);
+            ownScheduleCursor = tick + 1;
+        }
+    }
+    /** Predict exactly one frame: schedule own input (delay-shifted), step, extend the head. */
+    function stepPredictedFrame() {
+        const active = session;
+        if (active === undefined) {
+            return;
+        }
+        const tick = predictedThrough;
+        scheduleOwnInputsThrough(tick + inputDelayTicks);
+        const inputs = [];
+        for (let s = 0; s < playerCount; s += 1) {
+            const encoded = inputForSlot(s, tick);
+            inputs.push(encoded);
+            active.setInput(s, decodeInputSafe(encoded));
+        }
+        timeline[tick] = inputs;
+        active.stepFrames(1);
+        predictedThrough = tick + 1;
+    }
+    function simulate(from) {
+        const active = session;
+        if (active === undefined) {
+            return;
+        }
+        active.restoreToFrame(from);
+        for (let tick = from; tick < predictedThrough; tick += 1) {
+            const inputs = [];
+            for (let s = 0; s < playerCount; s += 1) {
+                const encoded = inputForSlot(s, tick);
+                inputs.push(encoded);
+                active.setInput(s, decodeInputSafe(encoded));
+            }
+            timeline[tick] = inputs;
+            active.stepFrames(1);
+        }
+    }
+    function pump() {
+        if (session === undefined) {
+            return;
+        }
+        flushOutgoingTransfer();
+        while (predictedThrough <= appliedThrough + maxPredictionTicks) {
+            stepPredictedFrame();
+        }
+    }
+    function pumpPaced(nowMs) {
+        flushOutgoingTransfer();
+        maybeSendPing(nowMs);
+        if (session === undefined || frameMs <= 0) {
+            lastPumpPacedMs = nowMs;
+            return;
+        }
+        if (lastPumpPacedMs === undefined) {
+            lastPumpPacedMs = nowMs;
+            return;
+        }
+        updateTimescale(nowMs);
+        pacingAccumulatorMs += Math.max(0, nowMs - lastPumpPacedMs) * timescale;
+        lastPumpPacedMs = nowMs;
+        let steps = Math.floor(pacingAccumulatorMs / frameMs);
+        pacingAccumulatorMs -= steps * frameMs;
+        if (steps > maxStepsPerPump) {
+            // Shed the debt instead of bursting later (a backgrounded-tab stall must
+            // not replay as a violent catch-up sprint).
+            steps = maxStepsPerPump;
+            pacingAccumulatorMs = 0;
+        }
+        for (let i = 0; i < steps; i += 1) {
+            if (predictedThrough > appliedThrough + maxPredictionTicks) {
+                // Prediction cap: the authority is the missing party, not local time —
+                // drop the debt so its arrival doesn't trigger a burst.
+                pacingAccumulatorMs = 0;
+                break;
+            }
+            stepPredictedFrame();
+        }
+    }
+    function sendInput(tick, input) {
+        options.transport.send(encodeDeterministicSessionMessage({ kind: 'input', slot, tick, input, attempt: 0 }));
+    }
+    function confirmedStateChecksum(frame) {
+        const active = session;
+        if (active === undefined) {
+            return '';
+        }
+        active.restoreToFrame(frame);
+        return String(defaultChecksum(active.getState()));
+    }
+    function applyConfirmedFrames(frames) {
+        for (const frame of frames) {
+            if (frame.tick > appliedThrough) {
+                confirmed.set(frame.tick, frame.inputs);
+            }
+        }
+        while (confirmed.has(appliedThrough + 1)) {
+            const tick = appliedThrough + 1;
+            const confInputs = confirmed.get(tick);
+            const predInputs = timeline[tick];
+            if (predInputs === undefined || canonicalStringify(confInputs) !== canonicalStringify(predInputs)) {
+                timeline[tick] = confInputs.slice();
+                if (predictedThrough > tick) {
+                    // Rollback: we had already predicted this tick and the confirmed inputs differ.
+                    rollbacks += 1;
+                    maxRollbackDepth = Math.max(maxRollbackDepth, predictedThrough - tick);
+                    simulate(tick);
+                }
+                else {
+                    // Confirm leads prediction (a lagging client): the authority confirmed a tick we had not
+                    // predicted yet. Extend the predicted head and apply the confirmed inputs so the session
+                    // actually advances through it — otherwise appliedThrough would outrun the simulated state.
+                    predictedThrough = tick + 1;
+                    simulate(tick);
+                }
+            }
+            for (let s = 0; s < playerCount; s += 1) {
+                lastConfirmedBySlot[s] = confInputs[s];
+            }
+            appliedThrough = tick;
+        }
+        autoReportCrossedCadences();
+    }
+    // ── M5.5: cadence-aligned checksum reports (quorum food + desync telemetry) ──
+    function autoReportCrossedCadences() {
+        let next = (Math.floor(lastAutoReportedTick / checksumCadenceTicks) + 1) * checksumCadenceTicks;
+        let reported = false;
+        while (next <= appliedThrough) {
+            sendChecksumReportAt(next);
+            lastAutoReportedTick = next;
+            reported = true;
+            next += checksumCadenceTicks;
+        }
+        // Netcode telemetry rides the same cadence (G8) — only once RTT exists,
+        // so step-counted tests (which never drive pumpPaced) stay silent.
+        if (reported && rttMs >= 0 && role !== 'spectator') {
+            options.transport.send(encodeDeterministicSessionMessage({
+                kind: 'net-stats',
+                slot,
+                tick: appliedThrough,
+                rttMs: Math.round(rttMs),
+                rollbacks,
+                maxRollbackDepth,
+                timescalePermille: Math.round(timescale * 1000),
+                inputDelayTicks,
+            }));
+        }
+    }
+    /**
+     * Report the confirmed-state checksum at `tick`, read from the rolling
+     * snapshot buffer — NOT via restoreToFrame, which would rewind the live
+     * session out from under prediction. Buffer state is the serialize
+     * round-trip of the live state, i.e. exactly what a snapshot joiner will
+     * hydrate, so quorum comparisons are round-trip-consistent by construction.
+     * Ticks that fell out of the buffer are skipped (the client simply is not
+     * donor-eligible for them).
+     */
+    function sendChecksumReportAt(tick) {
+        const active = session;
+        // Spectators hold no slot — the authority would drop their reports anyway.
+        if (active === undefined || tick < 0 || role === 'spectator') {
+            return;
+        }
+        const snapshot = active.getSnapshot(tick + 1);
+        if (snapshot === undefined) {
+            return;
+        }
+        options.transport.send(encodeDeterministicSessionMessage({
+            kind: 'checksum-report',
+            slot,
+            tick,
+            checksum: defaultChecksum(snapshot.state),
+        }));
+        reportedTicks.push(tick);
+        if (reportedTicks.length > REPORTED_TICKS_RETAINED) {
+            reportedTicks.shift();
+        }
+    }
+    // ── M5.5: snapshot late-join wire handling (donor + joiner roles) ──
+    function handleSnapshotWireMessage(text) {
+        let envelope;
+        try {
+            envelope = decodeDeterministicLocalAuthorityWireEnvelope(text);
+        }
+        catch {
+            return;
+        }
+        if (envelope.kind === 'snapshot-request') {
+            handleSnapshotRequest(envelope.payload);
+            return;
+        }
+        if (envelope.kind === 'snapshot-offer') {
+            transferCollector.offer(envelope.payload);
+            return;
+        }
+        if (envelope.kind === 'snapshot-chunk') {
+            transferCollector.chunk(envelope.payload);
+            return;
+        }
+        if (envelope.kind === 'snapshot-complete') {
+            const completed = transferCollector.complete(envelope.payload);
+            if (completed.accepted) {
+                applyCollectedTransfer(completed.transfer);
+            }
+        }
+    }
+    /** Donor role: answer with the smallest self-reported tick the buffer can still export. */
+    function handleSnapshotRequest(payload) {
+        const active = session;
+        if (active === undefined) {
+            return;
+        }
+        const requestIdentity = payload.identity;
+        if (typeof requestIdentity !== 'object' ||
+            requestIdentity === null ||
+            requestIdentity.descriptorHash !== descriptorHash) {
+            return;
+        }
+        const minFrame = payload.minFrame;
+        if (typeof minFrame !== 'number' || !Number.isInteger(minFrame)) {
+            return;
+        }
+        const minTick = minFrame - 1;
+        const candidates = reportedTicks.filter((tick) => tick >= minTick).sort((a, b) => a - b);
+        for (const tick of candidates) {
+            const snapshot = active.getSnapshot(tick + 1);
+            const confirmedAtTick = timeline[tick];
+            if (snapshot === undefined || confirmedAtTick === undefined) {
+                continue;
+            }
+            const bytes = encodeDeterministicStateSnapshot({
+                v: 1,
+                tick,
+                sessionFrame: tick + 1,
+                stateBytes: bytesToBase64(snapshot.stateBytes),
+                randomState: snapshot.randomState,
+                stateChecksum: defaultChecksum(snapshot.state),
+                confirmedInputs: confirmedAtTick.map((input) => cloneCanonical(input)),
+            });
+            donorTransferCounter += 1;
+            const transfer = createSnapshotTransferFromBytes(bytes, {
+                identity: { descriptorHash, schemaHash },
+                frame: tick + 1,
+                transferId: `donor:${slot}:${tick}:${donorTransferCounter}`,
+            });
+            let sequence = donorTransferCounter * 1000;
+            options.transport.send(createDeterministicLocalAuthoritySnapshotOfferEnvelope(sequence++, transfer));
+            for (let index = 0; index < transfer.chunks.length; index += 1) {
+                outgoingTransferQueue.push(createDeterministicLocalAuthoritySnapshotChunkEnvelope(sequence++, transfer, index));
+            }
+            outgoingTransferQueue.push(createDeterministicLocalAuthoritySnapshotCompleteEnvelope(sequence++, transfer.transferId));
+            return;
+        }
+        // Nothing exportable: stay silent — the authority times out and rotates donors.
+    }
+    /** Paced donor upload: a burst of large chunks must not trip host flood limits. */
+    function flushOutgoingTransfer() {
+        for (let i = 0; i < TRANSFER_SENDS_PER_PUMP && outgoingTransferQueue.length > 0; i += 1) {
+            const text = outgoingTransferQueue.shift();
+            if (text !== undefined) {
+                options.transport.send(text);
+            }
+        }
+    }
+    /**
+     * Joiner role: hydrate from an authority-forwarded snapshot. Stale transfers
+     * (reconnect refills the client is already past) are silently discarded;
+     * identity or state-checksum mismatches are FAIL-LOUD — a wrong room, wrong
+     * game build, or forged snapshot must never seat a desynced player.
+     */
+    function applyCollectedTransfer(collected) {
+        const active = session;
+        if (active === undefined) {
+            return;
+        }
+        const decoded = decodeDeterministicStateSnapshot(collected.snapshotBytes);
+        if (!decoded.ok || decoded.snapshot.sessionFrame !== collected.frame) {
+            return;
+        }
+        const snapshot = decoded.snapshot;
+        if (snapshot.tick <= appliedThrough) {
+            return;
+        }
+        if (collected.identity.descriptorHash !== descriptorHash) {
+            throw new SyncplayError('Snapshot descriptorHash does not match this room', {
+                code: 'client.snapshot-identity-mismatch',
+                frame: snapshot.sessionFrame,
+            });
+        }
+        if (collected.identity.schemaHash !== undefined && collected.identity.schemaHash !== schemaHash) {
+            throw new SyncplayError('Snapshot schemaHash does not match this game build', {
+                code: 'client.snapshot-identity-mismatch',
+                frame: snapshot.sessionFrame,
+            });
+        }
+        if (snapshot.confirmedInputs.length !== playerCount) {
+            throw new SyncplayError('Snapshot confirmedInputs do not cover every player slot', {
+                code: 'client.snapshot-inputs-mismatch',
+                frame: snapshot.sessionFrame,
+            });
+        }
+        active.restoreSnapshot({
+            frame: snapshot.sessionFrame,
+            stateBytes: base64ToBytes(snapshot.stateBytes),
+            randomState: snapshot.randomState,
+            inputs: snapshot.confirmedInputs.map((input) => decodeInputSafe(input)),
+        });
+        const actualChecksum = defaultChecksum(active.getState());
+        if (actualChecksum !== snapshot.stateChecksum) {
+            throw new SyncplayError('Hydrated snapshot state does not match its declared checksum', {
+                code: 'client.snapshot-state-mismatch',
+                frame: snapshot.sessionFrame,
+            });
+        }
+        appliedThrough = snapshot.tick;
+        predictedThrough = snapshot.tick + 1;
+        // Never send input for ticks at/below the hydration point — they are
+        // already confirmed. Anything the cursor had scheduled beyond it stands.
+        ownScheduleCursor = Math.max(ownScheduleCursor, snapshot.tick + 1);
+        lastConfirmedBySlot = snapshot.confirmedInputs.map((input) => cloneCanonical(input));
+        timeline.length = 0;
+        timeline[snapshot.tick] = lastConfirmedBySlot.slice();
+        for (const key of [...ownInputs.keys()]) {
+            if (key <= snapshot.tick)
+                ownInputs.delete(key);
+        }
+        for (const key of [...confirmed.keys()]) {
+            if (key <= snapshot.tick)
+                confirmed.delete(key);
+        }
+        lastAutoReportedTick = Math.max(lastAutoReportedTick, snapshot.tick);
+        // Frames that arrived before hydration are buffered in `confirmed` — the
+        // normal contiguous-apply drains the tail from here.
+        applyConfirmedFrames([]);
+    }
+    return {
+        get slot() {
+            return slot;
+        },
+        get role() {
+            return role;
+        },
+        get ready() {
+            return session !== undefined;
+        },
+        get predictedThrough() {
+            return predictedThrough;
+        },
+        get appliedThrough() {
+            return appliedThrough;
+        },
+        get rollbacks() {
+            return rollbacks;
+        },
+        get netStats() {
+            return {
+                rttMs: rttMs < 0 ? -1 : Math.round(rttMs),
+                timescalePermille: Math.round(timescale * 1000),
+                inputDelayTicks,
+                rollbacks,
+                maxRollbackDepth,
+            };
+        },
+        whenReady() {
+            return readyPromise;
+        },
+        pump,
+        pumpPaced,
+        reportChecksum() {
+            if (session === undefined || appliedThrough < 0) {
+                return;
+            }
+            sendChecksumReportAt(appliedThrough);
+        },
+        confirmedStateChecksum,
+        exportReplay() {
+            if (session === undefined) {
+                throw new Error('networked client has not started');
+            }
+            return session.exportReplay();
+        },
+    };
+}