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

package/dist/authority-room.js

@@ -0,0 +1,701 @@
+import { defaultChecksum } from './canonical.js';
+import { invariant } from './errors.js';
+import { createInputAuthority } from './input-authority.js';
+import { createDeterministicLocalAuthoritySnapshotChunkEnvelope, createDeterministicLocalAuthoritySnapshotCompleteEnvelope, createDeterministicLocalAuthoritySnapshotOfferEnvelope, createDeterministicLocalAuthoritySnapshotRequestEnvelope, decodeDeterministicLocalAuthorityWireEnvelope, } from './local-authority-wire.js';
+import { DEFAULT_SNAPSHOT_CHUNK_SIZE, createSnapshotTransferCollector, createSnapshotTransferFromBytes, decodeDeterministicStateSnapshot, deterministicRoomDescriptorHash, } from './session-snapshot.js';
+import { decodeDeterministicSessionMessage, encodeDeterministicSessionMessage } from './session-wire.js';
+const DEFAULT_SESSION_MSG_TYPE = 'rdm';
+/** One hour at 60 Hz — see DeterministicAuthorityRoomConfig.historyRetentionTicks. */
+const DEFAULT_HISTORY_RETENTION_TICKS = 216_000;
+/** Frames per history-replay unicast. Bounds message size during catch-up. */
+const HISTORY_CHUNK_FRAMES = 500;
+/** One minute at 60 Hz — see DeterministicAuthorityRoomConfig.snapshotCadenceTicks. */
+const DEFAULT_SNAPSHOT_CADENCE_TICKS = 3600;
+/** Ten seconds at 60 Hz — see DeterministicAuthorityRoomConfig.transferTimeoutTicks. */
+const DEFAULT_TRANSFER_TIMEOUT_TICKS = 600;
+export function createDeterministicAuthorityRoom(transport, config) {
+    const sessionMsgType = config.sessionMsgType ?? DEFAULT_SESSION_MSG_TYPE;
+    const historyRetentionTicks = config.historyRetentionTicks ?? DEFAULT_HISTORY_RETENTION_TICKS;
+    const authority = createInputAuthority({
+        playerCount: config.playerCount,
+        hardToleranceTicks: config.hardToleranceTicks,
+        neutralInput: config.neutralInput,
+        maxFutureTicks: config.maxFutureTicks ?? 256,
+        // Retention serves two masters: the per-tick redundancy rebroadcast window
+        // (never below redundancyWindow*4) and late-join/rejoin history replay
+        // (historyRetentionTicks — explicit caller choice wins; the generous floor
+        // lives in DEFAULT_HISTORY_RETENTION_TICKS, not here, so tests can shrink it).
+        retainedConfirmedFrames: Math.max(historyRetentionTicks, config.redundancyWindowTicks * 4),
+        ...(config.restoreFrom === undefined
+            ? {}
+            : { restoreFrom: { confirmedThrough: config.restoreFrom.confirmedThrough, frames: config.restoreFrom.tail } }),
+    });
+    const slotByPlayer = new Map();
+    // G11 spectators: read-only connections with no slot. Their input /
+    // checksum-report / net-stats envelopes are already dropped by the
+    // slot-ownership check in onPlayerMessage.
+    const spectators = new Set();
+    // Rejoin reclaim map: every playerId ever seated, permanently bound to its
+    // slot. A returning player re-attaches to the SAME slot (their inputs must
+    // keep attributing to the same sim entity), and can never be treated as a
+    // fresh joiner stealing capacity.
+    const everSlotByPlayer = new Map();
+    // Per-tick client checksum reports, for desync detection (telemetry, never enforcement).
+    const checksumReports = new Map();
+    const desyncWindow = Math.max(config.redundancyWindowTicks * 8, 512);
+    // Monotonic — slot numbers are assigned in join order and never reused, even after a player
+    // leaves. Using slotByPlayer.size would recycle a departed player's slot onto the next joiner,
+    // colliding with a still-present player and orphaning the vacated slot.
+    let assignedSlots = 0;
+    let now = -1;
+    // M5.5 snapshot acquisition state. The authority stores at most one validated
+    // snapshot and runs at most one donor transfer at a time.
+    const snapshotCadenceTicks = config.snapshotCadenceTicks ?? DEFAULT_SNAPSHOT_CADENCE_TICKS;
+    const transferTimeoutTicks = config.transferTimeoutTicks ?? DEFAULT_TRANSFER_TIMEOUT_TICKS;
+    const roomDescriptorHash = deterministicRoomDescriptorHash({
+        seed: config.seed,
+        playerCount: config.playerCount,
+        tickRateHz: config.tickRateHz,
+        hardToleranceTicks: config.hardToleranceTicks,
+    });
+    let storedSnapshot;
+    let pendingTransfer;
+    let nextCadenceTarget = snapshotCadenceTicks;
+    let wireSequence = 0;
+    let donorCursor = 0;
+    let forwardCounter = 0;
+    let reportsDirty = false;
+    // G8 netcode telemetry: cumulative substituted-input ticks per slot (counted
+    // once per newly-confirmed tick) and the latest client-reported stats.
+    const substitutedTicksBySlot = new Map();
+    const clientNetStatsBySlot = new Map();
+    let substitutionCountedThrough = -1;
+    // Highest tick ever included in a confirmed-input broadcast — the anchor
+    // that guarantees frontier jumps larger than the redundancy window can
+    // never skip a tick out of the broadcast stream (see onTick).
+    let broadcastThrough = -1;
+    // True for a crash-recovered room: reconnects must re-issue session-start so
+    // a surviving client (whose timeline forked past the restored frontier)
+    // takes its full-reset path instead of waiting on ticks that will re-confirm
+    // differently.
+    let restoredRoom = false;
+    if (config.restoreFrom !== undefined) {
+        const restore = config.restoreFrom;
+        for (const [playerId, slot] of Object.entries(restore.everSlots)) {
+            invariant(Number.isInteger(slot) && slot >= 0 && slot < config.playerCount, 'restored everSlots entry is outside the player count', 'authority-room.restore-slot');
+            everSlotByPlayer.set(playerId, slot);
+            assignedSlots = Math.max(assignedSlots, slot + 1);
+        }
+        for (const playerId of restore.seatedPlayers) {
+            const slot = everSlotByPlayer.get(playerId);
+            invariant(slot !== undefined, 'restored seated player is not in everSlots', 'authority-room.restore-seated');
+            slotByPlayer.set(playerId, slot);
+        }
+        invariant(Number.isInteger(restore.now) && restore.now >= restore.confirmedThrough, 'restored now must be at or past the restored frontier', 'authority-room.restore-now');
+        now = restore.now;
+        if (restore.snapshotBytes !== undefined) {
+            const decoded = decodeDeterministicStateSnapshot(restore.snapshotBytes);
+            invariant(decoded.ok, 'restored snapshotBytes do not decode', 'authority-room.restore-snapshot');
+            // With preserveFullHistory the persisted tail reaches back to tick 0
+            // (below the snapshot); a tail starting ABOVE the snapshot tick would
+            // leave an unreplayable gap and must still fail loud.
+            invariant(restore.tail[0] !== undefined && restore.tail[0].tick <= decoded.snapshot.tick, 'restored tail must start at or below the snapshot tick', 'authority-room.restore-tail');
+            // A tampered/corrupt record whose snapshot sits beyond the restored
+            // frontier would hydrate joiners into the authority's future, silently
+            // dropping confirms until the frontier catches up — fail loud instead.
+            invariant(decoded.snapshot.tick <= restore.confirmedThrough, 'restored snapshot must not be beyond the restored frontier', 'authority-room.restore-snapshot-frontier');
+            storedSnapshot = {
+                tick: decoded.snapshot.tick,
+                snapshotChecksum: defaultChecksum(restore.snapshotBytes),
+                snapshotBytes: restore.snapshotBytes,
+                identity: {
+                    descriptorHash: roomDescriptorHash,
+                    ...(restore.schemaHash === undefined ? {} : { schemaHash: restore.schemaHash }),
+                },
+            };
+        }
+        else {
+            invariant(restore.tail[0]?.tick === 0, 'a snapshot-less restore requires history reaching tick 0', 'authority-room.restore-history');
+        }
+        nextCadenceTarget = (Math.floor(restore.confirmedThrough / snapshotCadenceTicks) + 1) * snapshotCadenceTicks;
+        // Restored history is served per-player by resyncSeatedPlayers — the
+        // broadcast anchor starts at the restored frontier, not tick 0.
+        broadcastThrough = restore.confirmedThrough;
+        restoredRoom = true;
+    }
+    function sendSessionStart(playerId, slot, role = 'player') {
+        transport.sendTo(playerId, sessionMsgType, encodeDeterministicSessionMessage({
+            kind: 'session-start',
+            slot,
+            playerCount: config.playerCount,
+            seed: config.seed,
+            tickRateHz: config.tickRateHz,
+            hardToleranceTicks: config.hardToleranceTicks,
+            role,
+        }));
+    }
+    /**
+     * Unicast the full confirmed-input history (tick 0 .. confirmedThrough) so a
+     * late joiner / rejoiner can fast-forward its sim deterministically. Rides
+     * the existing `confirmed-input` wire kind, chunked — clients apply frames
+     * contiguously and dedupe already-applied ticks, so this needs no protocol
+     * change and is idempotent for reconnects.
+     */
+    function sendHistoryTo(playerId, fromTick) {
+        if (authority.confirmedThrough < 0)
+            return;
+        // History may be pruned below a validated snapshot: start at the earliest
+        // retained tick (a snapshot-hydrated joiner needs nothing below it). A
+        // snapshot-plan caller passes the snapshot tick explicitly — with
+        // preserveFullHistory the retained history reaches tick 0 but the joiner
+        // still needs only the post-snapshot tail (M2: keeps catch-up O(tail),
+        // never O(match length)).
+        const start = Math.max(0, authority.earliestRetainedTick, fromTick ?? 0);
+        for (let from = start; from <= authority.confirmedThrough; from += HISTORY_CHUNK_FRAMES) {
+            const to = Math.min(from + HISTORY_CHUNK_FRAMES - 1, authority.confirmedThrough);
+            const frames = [];
+            for (let tick = from; tick <= to; tick += 1) {
+                const frame = authority.confirmedFrame(tick);
+                if (frame !== undefined)
+                    frames.push(frame);
+            }
+            if (frames.length === 0)
+                continue;
+            transport.sendTo(playerId, sessionMsgType, encodeDeterministicSessionMessage({ kind: 'confirmed-input', authorityTick: now, frames }));
+        }
+    }
+    /** True when tick 0 is still replayable (a joiner can reconstruct from the start). */
+    function historyReachesTickZero() {
+        return authority.confirmedThrough < 0 || authority.confirmedFrame(0) !== undefined;
+    }
+    /**
+     * How a joiner/rejoiner can reconstruct state. Snapshot wins when one is
+     * stored AND the input tail after it is contiguous (a stored snapshot whose
+     * tail was ring-pruned must reject rather than seat a joiner that would
+     * stall on the gap forever — fail loud).
+     */
+    function catchUpPlan() {
+        if (storedSnapshot !== undefined && authority.earliestRetainedTick <= storedSnapshot.tick + 1) {
+            return 'snapshot';
+        }
+        if (historyReachesTickZero()) {
+            return 'history';
+        }
+        return 'unavailable';
+    }
+    function sendCatchUpTo(playerId, plan, kind) {
+        if (plan === 'snapshot') {
+            sendStoredSnapshotTo(playerId);
+        }
+        sendHistoryTo(playerId, plan === 'snapshot' ? storedSnapshot?.tick : undefined);
+        const tailStart = Math.max(0, authority.earliestRetainedTick, plan === 'snapshot' ? (storedSnapshot?.tick ?? 0) : 0);
+        config.onCatchUpEvent?.({
+            playerId,
+            kind,
+            plan,
+            tailFrames: authority.confirmedThrough < 0 ? 0 : authority.confirmedThrough - tailStart + 1,
+            ...(storedSnapshot === undefined ? {} : { snapshotTick: storedSnapshot.tick }),
+        });
+    }
+    function sendStoredSnapshotTo(playerId) {
+        if (storedSnapshot === undefined)
+            return;
+        forwardCounter += 1;
+        const transfer = createSnapshotTransferFromBytes(storedSnapshot.snapshotBytes, {
+            identity: storedSnapshot.identity,
+            frame: storedSnapshot.tick + 1,
+            transferId: `snap:${storedSnapshot.tick}:${forwardCounter}`,
+            chunkSize: DEFAULT_SNAPSHOT_CHUNK_SIZE,
+        });
+        transport.sendTo(playerId, sessionMsgType, createDeterministicLocalAuthoritySnapshotOfferEnvelope(nextWireSequence(), transfer));
+        for (let index = 0; index < transfer.chunks.length; index += 1) {
+            transport.sendTo(playerId, sessionMsgType, createDeterministicLocalAuthoritySnapshotChunkEnvelope(nextWireSequence(), transfer, index));
+        }
+        transport.sendTo(playerId, sessionMsgType, createDeterministicLocalAuthoritySnapshotCompleteEnvelope(nextWireSequence(), transfer.transferId));
+    }
+    function nextWireSequence() {
+        wireSequence += 1;
+        return wireSequence;
+    }
+    function confirmedTail() {
+        if (authority.confirmedThrough < 0)
+            return [];
+        return authority.confirmedFrameRange(Math.max(0, authority.earliestRetainedTick), authority.confirmedThrough);
+    }
+    function resyncSeatedPlayers() {
+        for (const [playerId, slot] of slotByPlayer) {
+            const plan = catchUpPlan();
+            invariant(plan !== 'unavailable', 'a restored room must have a catch-up plan for seated players', 'authority-room.restore-catchup');
+            sendSessionStart(playerId, slot);
+            sendCatchUpTo(playerId, plan, 'resync');
+        }
+    }
+    function onPlayerJoin(playerId) {
+        const existing = slotByPlayer.get(playerId);
+        if (existing !== undefined) {
+            return { accepted: false, reason: 'already-joined' };
+        }
+        // Rejoin: a previously-seated playerId reclaims its original slot and
+        // catches up from history. Sits BEFORE the capacity check — their seat was
+        // never given away (slots are never recycled).
+        const formerSlot = everSlotByPlayer.get(playerId);
+        if (formerSlot !== undefined) {
+            const rejoinPlan = catchUpPlan();
+            if (rejoinPlan === 'unavailable') {
+                return { accepted: false, reason: 'history-unavailable' };
+            }
+            slotByPlayer.set(playerId, formerSlot);
+            sendSessionStart(playerId, formerSlot);
+            sendCatchUpTo(playerId, rejoinPlan, 'rejoin');
+            return { accepted: true, slot: formerSlot, rejoined: true };
+        }
+        if (assignedSlots >= config.playerCount) {
+            return { accepted: false, reason: 'room-full' };
+        }
+        // Late joiner (clock already running): seat them only when state is still
+        // reconstructible — from a validated snapshot + input tail (M5.5), or from
+        // the full history when tick 0 is retained. Never desync silently.
+        const plan = catchUpPlan();
+        if (plan === 'unavailable') {
+            return { accepted: false, reason: 'history-unavailable' };
+        }
+        const slot = assignedSlots;
+        assignedSlots += 1;
+        slotByPlayer.set(playerId, slot);
+        everSlotByPlayer.set(playerId, slot);
+        sendSessionStart(playerId, slot);
+        sendCatchUpTo(playerId, plan, 'join');
+        return { accepted: true, slot };
+    }
+    /**
+     * Seat a connection as a SPECTATOR (G11): no slot, no input authority — a
+     * read-only session that hydrates like a late joiner (session-start with
+     * role 'spectator' + snapshot/history catch-up) and follows the live
+     * confirmed-input broadcast. Idempotent for an already-seated spectator
+     * (re-greet + refill). Returns false when the player holds a real slot or
+     * no catch-up plan exists.
+     */
+    function onSpectatorJoin(playerId) {
+        if (slotByPlayer.has(playerId))
+            return false;
+        const plan = catchUpPlan();
+        if (plan === 'unavailable')
+            return false;
+        spectators.add(playerId);
+        sendSessionStart(playerId, -1, 'spectator');
+        sendCatchUpTo(playerId, plan, 'join');
+        return true;
+    }
+    function onPlayerReconnected(playerId) {
+        // A spectator reconnect is a full re-greet: its timeline may have forked
+        // arbitrarily far and it holds no slot the redundancy window protects.
+        if (spectators.has(playerId)) {
+            onSpectatorJoin(playerId);
+            return;
+        }
+        const slot = slotByPlayer.get(playerId);
+        if (slot === undefined)
+            return;
+        // Post-restore, a reattaching client's timeline forked past the restored
+        // frontier — re-greet it so the client takes its full-reset + re-hydrate
+        // path rather than stalling on ticks that will re-confirm differently.
+        if (restoredRoom) {
+            sendSessionStart(playerId, slot);
+        }
+        // Socket swapped mid-match: refill anything missed while offline. The
+        // redundancy window only covers ~redundancyWindowTicks of outage, so a
+        // longer blip needs the history path; dedupe on the client makes the
+        // overlap free. In a pruned room the refill alone can have a gap for a
+        // client that fell behind the snapshot tick, so the stored snapshot rides
+        // along — the client applies it only when it is ahead of its own state.
+        const reconnectPlan = !historyReachesTickZero() && storedSnapshot !== undefined ? 'snapshot' : 'history';
+        sendCatchUpTo(playerId, reconnectPlan, 'reconnect');
+    }
+    function onPlayerMessage(playerId, envelope) {
+        // Fail closed: unknown/malformed messages are dropped. Snapshot transfer
+        // envelopes are the OTHER frozen wire family (schemaVersion vs v field) —
+        // the session decoder rejects them, and they get a second, equally
+        // fail-closed decode below.
+        const decoded = decodeDeterministicSessionMessage(envelope);
+        if (!decoded.ok) {
+            handleSnapshotWireMessage(playerId, envelope);
+            return;
+        }
+        const message = decoded.message;
+        // Clock sync (G1/G2): echo the authority tick so clients can estimate
+        // drift + RTT and pace themselves. Answered for any connected transport
+        // (no slot needed) — the reply carries nothing a spectator couldn't infer
+        // from confirmed-input broadcasts anyway.
+        if (message.kind === 'time-sync-ping') {
+            transport.sendTo(playerId, sessionMsgType, encodeDeterministicSessionMessage({
+                kind: 'time-sync-pong',
+                clientSendTick: message.clientSendTick,
+                nonce: message.nonce,
+                authorityTick: now,
+            }));
+            return;
+        }
+        if (message.kind !== 'input' && message.kind !== 'checksum-report' && message.kind !== 'net-stats') {
+            return;
+        }
+        const slot = slotByPlayer.get(playerId);
+        // Server owns the slot mapping — a client cannot act for a slot it was not assigned.
+        if (slot === undefined || message.slot !== slot) {
+            return;
+        }
+        if (message.kind === 'input') {
+            authority.receiveInput(slot, message.tick, message.input);
+        }
+        else if (message.kind === 'checksum-report') {
+            recordChecksumReport(slot, message.tick, message.checksum);
+        }
+        else {
+            clientNetStatsBySlot.set(slot, {
+                tick: message.tick,
+                rttMs: message.rttMs,
+                rollbacks: message.rollbacks,
+                maxRollbackDepth: message.maxRollbackDepth,
+                timescalePermille: message.timescalePermille,
+                inputDelayTicks: message.inputDelayTicks,
+            });
+        }
+    }
+    function recordChecksumReport(slot, tick, checksum) {
+        let reports = checksumReports.get(tick);
+        if (reports === undefined) {
+            reports = new Map();
+            checksumReports.set(tick, reports);
+            if (checksumReports.size > desyncWindow) {
+                // Evict the OLDEST stored report. Clients sample checksums sparsely, so
+                // the keyed form `delete(tick - desyncWindow)` usually names a tick that
+                // was never stored and the map would grow for the whole match. Insertion
+                // order ≈ tick order, so the first key is the oldest.
+                const oldestTick = checksumReports.keys().next().value;
+                if (oldestTick !== undefined) {
+                    checksumReports.delete(oldestTick);
+                }
+            }
+        }
+        // Detection only: a differing checksum for the same tick means a client has desynced itself.
+        if (config.onDesync !== undefined) {
+            for (const [otherSlot, otherChecksum] of reports) {
+                if (otherSlot !== slot && otherChecksum !== checksum) {
+                    config.onDesync({
+                        tick,
+                        slot,
+                        checksum,
+                        conflictingSlot: otherSlot,
+                        conflictingChecksum: otherChecksum,
+                        reportsAtTick: { ...Object.fromEntries(reports), [slot]: checksum },
+                    });
+                }
+            }
+        }
+        reports.set(slot, checksum);
+        reportsDirty = true;
+    }
+    // ── M5.5 snapshot acquisition ──
+    function handleSnapshotWireMessage(playerId, envelope) {
+        let parsed;
+        try {
+            parsed = decodeDeterministicLocalAuthorityWireEnvelope(envelope);
+        }
+        catch {
+            return;
+        }
+        if (parsed.kind !== 'snapshot-offer' && parsed.kind !== 'snapshot-chunk' && parsed.kind !== 'snapshot-complete') {
+            return;
+        }
+        // Only the designated donor may feed the pending transfer.
+        if (pendingTransfer === undefined || pendingTransfer.donorId !== playerId) {
+            return;
+        }
+        if (parsed.kind === 'snapshot-offer') {
+            const result = pendingTransfer.collector.offer(parsed.payload);
+            if (!result.accepted)
+                failPendingTransfer(result.reason);
+            return;
+        }
+        if (parsed.kind === 'snapshot-chunk') {
+            const result = pendingTransfer.collector.chunk(parsed.payload);
+            if (!result.accepted)
+                failPendingTransfer(result.reason);
+            return;
+        }
+        const completed = pendingTransfer.collector.complete(parsed.payload);
+        if (!completed.accepted) {
+            failPendingTransfer(completed.reason);
+            return;
+        }
+        validateAndStoreSnapshot(completed.transfer);
+    }
+    /**
+     * The trust gate (§M5.5): a donated snapshot is stored only when its
+     * self-declared state checksum matches the checksum-report of EVERY
+     * currently-connected player at that tick. The authority never runs game
+     * code — this cross-client quorum is what makes an opaque donated blob safe
+     * to hand to joiners (the joiner re-verifies after hydrating, too).
+     */
+    function validateAndStoreSnapshot(collected) {
+        if (pendingTransfer === undefined)
+            return;
+        const donorId = pendingTransfer.donorId;
+        const decoded = decodeDeterministicStateSnapshot(collected.snapshotBytes);
+        if (!decoded.ok) {
+            failPendingTransfer(`snapshot-payload-${decoded.reason}`);
+            return;
+        }
+        const snapshot = decoded.snapshot;
+        if (snapshot.sessionFrame !== collected.frame) {
+            failPendingTransfer('snapshot-frame-mismatch');
+            return;
+        }
+        if (snapshot.tick < pendingTransfer.minFrame - 1) {
+            failPendingTransfer('snapshot-below-min-frame');
+            return;
+        }
+        if (snapshot.tick > authority.confirmedThrough) {
+            failPendingTransfer('snapshot-beyond-frontier');
+            return;
+        }
+        if (collected.identity.descriptorHash !== roomDescriptorHash) {
+            failPendingTransfer('snapshot-descriptor-mismatch');
+            return;
+        }
+        const reports = checksumReports.get(snapshot.tick);
+        for (const slot of slotByPlayer.values()) {
+            const reported = reports?.get(slot);
+            if (reported === undefined) {
+                failPendingTransfer('snapshot-unvalidatable');
+                return;
+            }
+            if (reported !== snapshot.stateChecksum) {
+                failPendingTransfer('snapshot-quorum-mismatch');
+                return;
+            }
+        }
+        storedSnapshot = {
+            tick: snapshot.tick,
+            snapshotChecksum: collected.snapshotChecksum,
+            snapshotBytes: collected.snapshotBytes,
+            identity: collected.identity,
+        };
+        pendingTransfer = undefined;
+        // History below the snapshot tick is no longer needed by anyone: joiners
+        // hydrate at the snapshot and replay the tail. Keeping the tick-N frame
+        // itself guarantees the persisted tail is never empty (a snapshot can sit
+        // exactly at the frontier) — restore always has frames to rebuild from.
+        // With preserveFullHistory (G3 match logs) the ring buffer keeps tick 0;
+        // memory stays bounded by historyRetentionTicks.
+        if (config.preserveFullHistory !== true) {
+            authority.pruneConfirmedBefore(snapshot.tick);
+        }
+        nextCadenceTarget = (Math.floor(snapshot.tick / snapshotCadenceTicks) + 1) * snapshotCadenceTicks;
+        config.onSnapshotEvent?.({ kind: 'stored', donorId, tick: snapshot.tick });
+    }
+    function failPendingTransfer(reason) {
+        if (pendingTransfer === undefined)
+            return;
+        const failed = pendingTransfer;
+        pendingTransfer = undefined;
+        config.onSnapshotEvent?.({ kind: 'rejected', donorId: failed.donorId, reason });
+        // One immediate retry with the next donor; further failures wait for the
+        // next report-driven attempt so a broken room cannot request-storm.
+        if (!failed.isRetry) {
+            beginSnapshotAcquisition(true);
+        }
+    }
+    function beginSnapshotAcquisition(isRetry) {
+        const tick = pickSnapshotTick();
+        if (tick === undefined)
+            return;
+        const donorId = pickDonor();
+        if (donorId === undefined)
+            return;
+        pendingTransfer = {
+            donorId,
+            minFrame: tick + 1,
+            startedAt: now,
+            collector: createSnapshotTransferCollector(),
+            isRetry,
+        };
+        transport.sendTo(donorId, sessionMsgType, createDeterministicLocalAuthoritySnapshotRequestEnvelope(nextWireSequence(), { descriptorHash: roomDescriptorHash }, tick + 1));
+    }
+    /** Greatest confirmed tick past the stored snapshot that EVERY connected player has reported. */
+    function pickSnapshotTick() {
+        if (slotByPlayer.size === 0)
+            return undefined;
+        const floor = storedSnapshot?.tick ?? -1;
+        let best;
+        for (const [tick, reports] of checksumReports) {
+            if (tick <= floor || tick > authority.confirmedThrough)
+                continue;
+            if (best !== undefined && tick <= best)
+                continue;
+            let fullyReported = true;
+            for (const slot of slotByPlayer.values()) {
+                if (!reports.has(slot)) {
+                    fullyReported = false;
+                    break;
+                }
+            }
+            if (fullyReported)
+                best = tick;
+        }
+        return best;
+    }
+    function pickDonor() {
+        const donors = [...slotByPlayer.keys()];
+        if (donors.length === 0)
+            return undefined;
+        const donorId = donors[donorCursor % donors.length];
+        donorCursor += 1;
+        return donorId;
+    }
+    function maintainSnapshotAcquisition() {
+        if (pendingTransfer !== undefined) {
+            if (now - pendingTransfer.startedAt > transferTimeoutTicks) {
+                failPendingTransfer('snapshot-transfer-timeout');
+            }
+            return;
+        }
+        if (authority.confirmedThrough < nextCadenceTarget)
+            return;
+        if (!reportsDirty)
+            return;
+        reportsDirty = false;
+        beginSnapshotAcquisition(false);
+    }
+    function onPlayerLeave(playerId) {
+        spectators.delete(playerId);
+        // Fixed roster for v1 (late-join/reconnect is M5). Dropping the mapping stops accepting the
+        // departed player's input; their slot stays reserved because `assignedSlots` never decreases,
+        // so the authority substitutes for it rather than handing the number to a new joiner.
+        slotByPlayer.delete(playerId);
+        if (pendingTransfer?.donorId === playerId) {
+            failPendingTransfer('snapshot-donor-left');
+        }
+    }
+    function onTick() {
+        // Opt-in lobby semantics: hold the authority clock at -1 until EVERY slot
+        // has joined, so all clients start from tick 0 together. The DEFAULT is
+        // drop-in: the clock runs from the first join and later players catch up
+        // via the history replay in onPlayerJoin. `assignedSlots` is monotonic, so
+        // a mid-match leave never re-pauses a started room.
+        if (config.waitForFullRoom === true && assignedSlots < config.playerCount) {
+            return;
+        }
+        now += 1;
+        authority.advance(now);
+        maintainSnapshotAcquisition();
+        if (authority.confirmedThrough < 0) {
+            return;
+        }
+        // Count substitutions once per newly-confirmed tick (the broadcast below
+        // re-sends a redundancy window, so it cannot be the counting site).
+        for (let tick = substitutionCountedThrough + 1; tick <= authority.confirmedThrough; tick += 1) {
+            const frame = authority.confirmedFrame(tick);
+            if (frame === undefined)
+                continue;
+            for (const slot of frame.substitutedSlots) {
+                substitutedTicksBySlot.set(slot, (substitutedTicksBySlot.get(slot) ?? 0) + 1);
+            }
+        }
+        substitutionCountedThrough = authority.confirmedThrough;
+        // The window alone is NOT enough: a burst of late-arriving inputs can
+        // confirm a jump of more than redundancyWindowTicks in a single tick, and
+        // a tick that misses its window is never sent again — every client stalls
+        // forever on the contiguity gap (the live-network freeze). Anchor the
+        // window start at the first never-broadcast tick so no confirmed tick can
+        // ever be skipped; the redundancy re-send behavior is unchanged.
+        const from = Math.max(0, Math.min(authority.confirmedThrough - config.redundancyWindowTicks + 1, broadcastThrough + 1));
+        // Catch-up bursts ride the same per-message frame bound as the history
+        // unicast path — an anchored burst must never produce an oversized frame
+        // for the host transport.
+        for (let chunkFrom = from; chunkFrom <= authority.confirmedThrough; chunkFrom += HISTORY_CHUNK_FRAMES) {
+            const chunkTo = Math.min(chunkFrom + HISTORY_CHUNK_FRAMES - 1, authority.confirmedThrough);
+            const frames = [];
+            for (let tick = chunkFrom; tick <= chunkTo; tick += 1) {
+                const frame = authority.confirmedFrame(tick);
+                if (frame !== undefined) {
+                    frames.push(frame);
+                }
+            }
+            if (frames.length === 0) {
+                continue;
+            }
+            transport.broadcast(sessionMsgType, encodeDeterministicSessionMessage({ kind: 'confirmed-input', authorityTick: now, frames }));
+        }
+        broadcastThrough = authority.confirmedThrough;
+    }
+    return {
+        get confirmedThrough() {
+            return authority.confirmedThrough;
+        },
+        playerCount: config.playerCount,
+        onPlayerJoin,
+        onSpectatorJoin,
+        onPlayerMessage,
+        onPlayerLeave,
+        onPlayerReconnected,
+        onTick,
+        snapshot() {
+            return {
+                confirmedThrough: authority.confirmedThrough,
+                now,
+                slots: Object.fromEntries(slotByPlayer),
+                everSlots: Object.fromEntries(everSlotByPlayer),
+                earliestRetainedTick: authority.earliestRetainedTick,
+                ...(storedSnapshot === undefined
+                    ? {}
+                    : {
+                        latestSnapshot: {
+                            tick: storedSnapshot.tick,
+                            snapshotChecksum: storedSnapshot.snapshotChecksum,
+                            descriptorHash: storedSnapshot.identity.descriptorHash,
+                            ...(storedSnapshot.identity.schemaHash === undefined ? {} : { schemaHash: storedSnapshot.identity.schemaHash }),
+                            byteLength: storedSnapshot.snapshotBytes.length,
+                        },
+                    }),
+            };
+        },
+        latestSnapshotBytes() {
+            return storedSnapshot?.snapshotBytes;
+        },
+        confirmedTail,
+        resyncSeatedPlayers,
+        resyncPlayer(playerId) {
+            const slot = slotByPlayer.get(playerId);
+            if (slot === undefined)
+                return false;
+            const plan = catchUpPlan();
+            if (plan === 'unavailable')
+                return false;
+            sendSessionStart(playerId, slot);
+            sendCatchUpTo(playerId, plan, 'resync');
+            return true;
+        },
+        netcodeStats() {
+            return {
+                confirmedThrough: authority.confirmedThrough,
+                substitutedTicksBySlot: Object.fromEntries(substitutedTicksBySlot),
+                clientStats: Object.fromEntries(clientNetStatsBySlot),
+            };
+        },
+        matchLog() {
+            if (authority.confirmedThrough < 0 || !historyReachesTickZero()) {
+                return undefined;
+            }
+            return {
+                v: 1,
+                seed: config.seed,
+                tickRateHz: config.tickRateHz,
+                playerCount: config.playerCount,
+                hardToleranceTicks: config.hardToleranceTicks,
+                confirmedThrough: authority.confirmedThrough,
+                everSlots: Object.fromEntries(everSlotByPlayer),
+                frames: authority.confirmedFrameRange(0, authority.confirmedThrough),
+            };
+        },
+    };
+}