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

package/dist/commands.js

@@ -0,0 +1,977 @@
+import { canonicalStringify, cloneCanonical, defaultChecksum } from './canonical.js';
+import { DeterministicRandom } from './random.js';
+export function createDeterministicCommandTimeline(config) {
+    validateCommandTimelineConfig(config);
+    const channels = new Map(config.channels.map((channel) => [channel.id, channel]));
+    const validAssetRefs = new Set(config.validAssetRefs ?? []);
+    const accepted = [];
+    const rejected = [];
+    const commandIds = new Set();
+    let currentFrame = config.currentFrame;
+    const recordTrusted = (command) => {
+        const rejection = validateCommand({ ...config, currentFrame }, channels, validAssetRefs, commandIds, command);
+        if (rejection !== undefined) {
+            rejected.push(rejection);
+            return rejection;
+        }
+        commandIds.add(command.id);
+        accepted.push(cloneCanonical({ ...command, submittedFrame: currentFrame }));
+        return undefined;
+    };
+    return {
+        get currentFrame() {
+            return currentFrame;
+        },
+        get accepted() {
+            return sortCommands(accepted).map((command) => cloneCanonical(command));
+        },
+        get rejected() {
+            return rejected.map((command) => cloneCanonical(command));
+        },
+        setCurrentFrame(frame) {
+            if (!Number.isInteger(frame) || frame < currentFrame) {
+                throw new Error(`Command timeline frame must advance monotonically from ${currentFrame} to ${frame}`);
+            }
+            currentFrame = frame;
+        },
+        record(command) {
+            return recordTrusted(command);
+        },
+        recordFromSlot(senderSlot, command) {
+            if (!Number.isInteger(senderSlot) || senderSlot !== command.slot) {
+                const rejection = reject(command, 'unauthorized-slot');
+                rejected.push(rejection);
+                return rejection;
+            }
+            return recordTrusted(command);
+        },
+        poll(frame, slot, channelId) {
+            return accepted
+                .filter((command) => command.frame === frame)
+                .filter((command) => slot === undefined || command.slot === slot)
+                .filter((command) => channelId === undefined || command.channelId === channelId)
+                .sort(compareCommands)
+                .map((command) => cloneCanonical(command));
+        },
+        snapshot() {
+            return createDeterministicCommandTimelineSnapshot({
+                currentFrame,
+                accepted,
+                rejected,
+            });
+        },
+        restore(snapshot) {
+            validateCommandTimelineSnapshot(snapshot);
+            const restoredAccepted = validateRestoredCommands(config, channels, validAssetRefs, snapshot);
+            const restoredRejected = snapshot.rejected.map((command) => cloneCanonical(command));
+            currentFrame = snapshot.currentFrame;
+            accepted.splice(0, accepted.length, ...restoredAccepted);
+            rejected.splice(0, rejected.length, ...restoredRejected);
+            commandIds.clear();
+            for (const command of accepted) {
+                commandIds.add(command.id);
+            }
+        },
+        checksum() {
+            return defaultChecksum({ accepted: sortCommands(accepted), rejected });
+        },
+    };
+}
+export function runDeterministicCommandTimelineMigrationFixture(players) {
+    if (!Number.isInteger(players) || players < 2 || players > 128) {
+        throw new Error('command timeline migration players must be between 2 and 128');
+    }
+    const channels = [
+        {
+            id: 'ability',
+            reliable: true,
+            allowPrediction: true,
+            maxPayloadBytes: 160,
+            maxFrameLead: 8,
+            fields: [
+                { name: 'assetRef', kind: 'asset-ref' },
+                { name: 'power', kind: 'integer', min: 0, max: 9 },
+                { name: 'targets', kind: 'player-slot[]', minItems: 1, maxItems: 4, min: 0, max: players - 1 },
+                { name: 'loadout', kind: 'object', fields: [
+                        { name: 'assetRef', kind: 'asset-ref' },
+                        { name: 'modifiers', kind: 'integer[]', minItems: 1, maxItems: 3, min: 0, max: 9 },
+                    ] },
+            ],
+        },
+    ];
+    const config = {
+        playerCount: players,
+        currentFrame: 12,
+        channels,
+        validAssetRefs: ['ability.dash', 'ability.shield'],
+    };
+    const timeline = createDeterministicCommandTimeline(config);
+    const preMigrationCommands = [
+        { id: 'cmd:12:1:dash', slot: 1, frame: 12, channelId: 'ability', payload: validAbilityPayload(1, players, 'ability.dash', 3) },
+        { id: 'cmd:12:1:shield', slot: 1, frame: 12, channelId: 'ability', payload: validAbilityPayload(1, players, 'ability.shield', 4) },
+        { id: 'cmd:13:0:dash', slot: 0, frame: 13, channelId: 'ability', payload: validAbilityPayload(0, players, 'ability.dash', 5) },
+    ];
+    for (const command of preMigrationCommands) {
+        timeline.record(command);
+    }
+    const snapshot = timeline.snapshot();
+    const restored = createDeterministicCommandTimeline({ ...config, currentFrame: 0 });
+    restored.restore(snapshot);
+    const snapshotChecksum = snapshot.checksum;
+    const restoredChecksum = restored.snapshot().checksum;
+    const restoredCurrentFrameBeforeAdvance = restored.currentFrame === snapshot.currentFrame;
+    const pollOrderStable = restored.poll(12, 1, 'ability').map((command) => command.id).join('|') === 'cmd:12:1:dash|cmd:12:1:shield';
+    const duplicateAfterRestoreRejected = restored.record({ ...preMigrationCommands[0] })?.reason === 'duplicate-command-id';
+    restored.setCurrentFrame(14);
+    const staleAfterRestoreRejected = restored.record({
+        id: 'cmd:stale',
+        slot: 0,
+        frame: 13,
+        channelId: 'ability',
+        payload: validAbilityPayload(0, players, 'ability.dash', 1),
+    })?.reason === 'stale-frame';
+    const futureAfterRestoreRejected = restored.record({
+        id: 'cmd:future',
+        slot: 0,
+        frame: 40,
+        channelId: 'ability',
+        payload: validAbilityPayload(0, players, 'ability.dash', 1),
+    })?.reason === 'future-frame';
+    const unauthorizedAfterRestoreRejected = restored.recordFromSlot(0, {
+        id: 'cmd:unauthorized',
+        slot: 1,
+        frame: 14,
+        channelId: 'ability',
+        payload: validAbilityPayload(1, players, 'ability.dash', 1),
+    })?.reason === 'unauthorized-slot';
+    const oversizedAfterRestoreRejected = restored.record({
+        id: 'cmd:oversized',
+        slot: 0,
+        frame: 14,
+        channelId: 'ability',
+        payload: { ...validAbilityPayload(0, players, 'ability.dash', 1), text: 'x'.repeat(200) },
+    })?.reason === 'oversized-payload';
+    const badSchemaAfterRestoreRejected = restored.record({
+        id: 'cmd:bad-schema',
+        slot: 0,
+        frame: 14,
+        channelId: 'ability',
+        payload: { assetRef: 'ability.dash', power: 1, targets: [0] },
+    })?.reason === 'bad-schema';
+    const badAssetRefAfterRestoreRejected = restored.record({
+        id: 'cmd:bad-asset',
+        slot: 0,
+        frame: 14,
+        channelId: 'ability',
+        payload: validAbilityPayload(0, players, 'ability.missing', 1),
+    })?.reason === 'bad-asset-ref';
+    const newCommandAcceptedAfterRestore = restored.record({
+        id: 'cmd:14:0:dash',
+        slot: 0,
+        frame: 14,
+        channelId: 'ability',
+        payload: validAbilityPayload(0, players, 'ability.dash', 7),
+    }) === undefined;
+    const rejectionCounts = restored.rejected.reduce((counts, rejection) => {
+        counts[rejection.reason] = (counts[rejection.reason] ?? 0) + 1;
+        return counts;
+    }, {});
+    const acceptedCommandIdsRestored = preMigrationCommands.every((command) => restored.accepted.some((candidate) => candidate.id === command.id));
+    const currentFrameRestored = snapshot.currentFrame === 12 && restoredCurrentFrameBeforeAdvance;
+    const orderedRejectionCounts = {};
+    const rejectionReasonOrder = [
+        'unauthorized-slot',
+        'stale-frame',
+        'future-frame',
+        'oversized-payload',
+        'bad-schema',
+        'bad-asset-ref',
+        'duplicate-command-id',
+        'duplicate-slot-frame-command',
+        'unknown-channel',
+        'insufficient-frame-lead',
+        'prediction-not-allowed',
+    ];
+    for (const reason of rejectionReasonOrder) {
+        const count = rejectionCounts[reason] ?? 0;
+        if (count > 0) {
+            orderedRejectionCounts[reason] = count;
+        }
+    }
+    const withoutChecksum = {
+        players,
+        acceptedBeforeMigration: snapshot.accepted.length,
+        acceptedAfterMigration: restored.accepted.length,
+        snapshotChecksum,
+        restoredChecksum,
+        finalChecksum: restored.checksum(),
+        pollOrderStable,
+        acceptedCommandIdsRestored,
+        currentFrameRestored,
+        duplicateAfterRestoreRejected,
+        staleAfterRestoreRejected,
+        futureAfterRestoreRejected,
+        unauthorizedAfterRestoreRejected,
+        oversizedAfterRestoreRejected,
+        badSchemaAfterRestoreRejected,
+        badAssetRefAfterRestoreRejected,
+        newCommandAcceptedAfterRestore,
+        rejectionCounts: orderedRejectionCounts,
+    };
+    const invariantChecks = [
+        pollOrderStable,
+        acceptedCommandIdsRestored,
+        currentFrameRestored,
+        duplicateAfterRestoreRejected,
+        staleAfterRestoreRejected,
+        futureAfterRestoreRejected,
+        unauthorizedAfterRestoreRejected,
+        oversizedAfterRestoreRejected,
+        badSchemaAfterRestoreRejected,
+        badAssetRefAfterRestoreRejected,
+        newCommandAcceptedAfterRestore,
+    ];
+    const result = evaluateDeterministicCommandTimelineMigrationResult({
+        invariantChecks,
+        snapshotChecksum,
+        restoredChecksum,
+        acceptedBeforeMigration: withoutChecksum.acceptedBeforeMigration,
+        acceptedAfterMigration: withoutChecksum.acceptedAfterMigration,
+        expectedAcceptedBeforeMigration: preMigrationCommands.length,
+    });
+    return {
+        result,
+        ...withoutChecksum,
+        checksum: defaultChecksum(withoutChecksum),
+    };
+}
+export function evaluateDeterministicCommandTimelineMigrationResult(input) {
+    return input.invariantChecks.every((value) => value)
+        && input.snapshotChecksum === input.restoredChecksum
+        && input.acceptedBeforeMigration === input.expectedAcceptedBeforeMigration
+        && input.acceptedAfterMigration === input.expectedAcceptedBeforeMigration + 1
+        ? 'pass'
+        : 'fail';
+}
+export function createDeterministicCommandTimelineSnapshot(snapshot) {
+    const normalized = {
+        currentFrame: snapshot.currentFrame,
+        accepted: sortCommands(snapshot.accepted).map((command) => cloneCanonical(command)),
+        rejected: [...snapshot.rejected].sort(compareRejectedCommands).map((command) => cloneCanonical(command)),
+    };
+    return {
+        ...normalized,
+        checksum: defaultChecksum(normalized),
+    };
+}
+export function runDeterministicCommandProtocolFixture(players, frames, seed) {
+    if (!Number.isInteger(players) || players < 1) {
+        throw new Error('command protocol players must be at least 1');
+    }
+    if (!Number.isInteger(frames) || frames < 1) {
+        throw new Error('command protocol frames must be at least 1');
+    }
+    const random = new DeterministicRandom(seed);
+    const channelDescriptors = [
+        {
+            id: 'ability',
+            reliable: true,
+            allowPrediction: true,
+            maxPayloadBytes: 128,
+            maxFrameLead: 12,
+            fields: [
+                { name: 'assetRef', kind: 'asset-ref' },
+                { name: 'power', kind: 'integer', min: 0, max: 9 },
+                { name: 'targets', kind: 'player-slot[]', minItems: 1, maxItems: 4, min: 0, max: Math.max(0, players - 1) },
+                { name: 'loadout', kind: 'object', fields: [
+                        { name: 'assetRef', kind: 'asset-ref' },
+                        { name: 'modifiers', kind: 'integer[]', minItems: 1, maxItems: 3, min: 0, max: 9 },
+                    ] },
+            ],
+        },
+        {
+            id: 'emote',
+            reliable: false,
+            allowPrediction: false,
+            maxPayloadBytes: 64,
+            minFrameLead: 1,
+            maxFrameLead: 4,
+            fields: [{ name: 'assetRef', kind: 'asset-ref' }],
+        },
+    ];
+    const channelById = new Map(channelDescriptors.map((channel) => [channel.id, channel]));
+    const timeline = createDeterministicCommandTimeline({
+        playerCount: players,
+        currentFrame: 0,
+        channels: channelDescriptors,
+        validAssetRefs: ['ability.dash', 'ability.shield', 'emote.wave'],
+    });
+    const delays = [];
+    const rollbackDepths = [];
+    let duplicateDrops = 0;
+    let multiCommandSameFrameAccepted = 0;
+    let multiCommandPollOrderStable = false;
+    let acceptedFutureCommands = 0;
+    let reliableDelivered = 0;
+    let reliableResent = 0;
+    let unreliableDropped = 0;
+    const transport = createDeterministicCommandTransport();
+    if (frames > 2) {
+        const fixtureFutureCommand = {
+            id: 'fixture:future-emote',
+            slot: 0,
+            frame: 2,
+            channelId: 'emote',
+            payload: { assetRef: 'emote.wave' },
+        };
+        timeline.record(fixtureFutureCommand);
+        acceptedFutureCommands += 1;
+        transport.send(fixtureFutureCommand, channelById.get(fixtureFutureCommand.channelId), 0);
+    }
+    if (frames > 1) {
+        const multiCommands = [
+            {
+                id: 'fixture:multi:reload',
+                slot: 0,
+                frame: 0,
+                channelId: 'ability',
+                payload: { assetRef: 'ability.shield', power: 3, targets: [0, 1], loadout: { assetRef: 'ability.shield', modifiers: [1, 2] } },
+            },
+            {
+                id: 'fixture:multi:dash',
+                slot: 0,
+                frame: 0,
+                channelId: 'ability',
+                payload: { assetRef: 'ability.dash', power: 7, targets: [0], loadout: { assetRef: 'ability.dash', modifiers: [3] } },
+            },
+        ];
+        for (const command of multiCommands) {
+            timeline.record(command);
+            multiCommandSameFrameAccepted += 1;
+            transport.send(command, channelById.get(command.channelId), 0);
+        }
+        multiCommandPollOrderStable = timeline.poll(0, 0, 'ability').map((command) => command.id).join('|')
+            === 'fixture:multi:dash|fixture:multi:reload';
+    }
+    for (let frame = 0; frame < frames; frame += 1) {
+        timeline.setCurrentFrame(frame);
+        for (let slot = 0; slot < players; slot += 1) {
+            if ((slot + frame + seed) % 17 !== 0) {
+                continue;
+            }
+            const delay = random.nextInt(0, 5);
+            if ((slot + frame + seed) % 53 === 0 && frame + 2 < frames) {
+                const futureCommand = {
+                    id: `${slot}:${frame}:emote`,
+                    slot,
+                    frame: frame + 2,
+                    channelId: 'emote',
+                    payload: { assetRef: 'emote.wave' },
+                };
+                timeline.record(futureCommand);
+                acceptedFutureCommands += 1;
+                transport.send(futureCommand, channelById.get(futureCommand.channelId), frame);
+            }
+            const command = {
+                id: `${slot}:${frame}:ability`,
+                slot,
+                frame,
+                channelId: 'ability',
+                payload: {
+                    assetRef: slot % 2 === 0 ? 'ability.dash' : 'ability.shield',
+                    power: (slot + frame) % 10,
+                    targets: [slot, (slot + 1) % players],
+                    loadout: {
+                        assetRef: slot % 2 === 0 ? 'ability.dash' : 'ability.shield',
+                        modifiers: [(slot + frame) % 4, (slot + frame + 1) % 4],
+                    },
+                },
+            };
+            timeline.record(command);
+            const rejection = timeline.record({ ...command, id: command.id });
+            duplicateDrops += Number(rejection?.reason === 'duplicate-command-id');
+            transport.send(command, channelById.get(command.channelId), frame);
+            delays.push(delay);
+            rollbackDepths.push(delay === 0 ? 0 : Math.min(8, delay + (frame % 3)));
+        }
+    }
+    const transportMetrics = transport.flush(frames + 16);
+    reliableDelivered = transportMetrics.reliableDelivered;
+    reliableResent = transportMetrics.reliableResent;
+    unreliableDropped = transportMetrics.unreliableDropped;
+    const hostileFrame = frames - 1;
+    const hostile = [
+        { id: 'bad-slot', slot: players, frame: hostileFrame, channelId: 'ability', payload: validAbilityPayload(0, players, 'ability.dash', 1) },
+        { id: 'stale', slot: 0, frame: -1, channelId: 'ability', payload: validAbilityPayload(0, players, 'ability.dash', 1) },
+        { id: 'future', slot: 0, frame: frames + 99, channelId: 'ability', payload: validAbilityPayload(0, players, 'ability.dash', 1) },
+        { id: 'oversized', slot: 0, frame: hostileFrame, channelId: 'ability', payload: { ...validAbilityPayload(0, players, 'ability.dash', 1), text: 'x'.repeat(200) } },
+        { id: 'bad-schema', slot: 0, frame: hostileFrame, channelId: 'ability', payload: 'bad' },
+        { id: 'bad-schema-missing', slot: 0, frame: hostileFrame, channelId: 'ability', payload: { assetRef: 'ability.dash', power: 1, targets: [0] } },
+        { id: 'bad-schema-extra', slot: 0, frame: hostileFrame, channelId: 'ability', payload: { ...validAbilityPayload(0, players, 'ability.dash', 1), extra: 1 } },
+        { id: 'bad-schema-range', slot: 0, frame: hostileFrame, channelId: 'ability', payload: validAbilityPayload(0, players, 'ability.dash', 99) },
+        { id: 'bad-schema-array-length', slot: 0, frame: hostileFrame, channelId: 'ability', payload: { ...validAbilityPayload(0, players, 'ability.dash', 1), targets: [0, 1, 2, 3, 4] } },
+        { id: 'bad-schema-nested-array-type', slot: 0, frame: hostileFrame, channelId: 'ability', payload: { ...validAbilityPayload(0, players, 'ability.dash', 1), loadout: { assetRef: 'ability.dash', modifiers: [1, 'bad'] } } },
+        { id: 'bad-asset', slot: 0, frame: hostileFrame, channelId: 'ability', payload: validAbilityPayload(0, players, 'missing.asset', 1) },
+        { id: 'bad-channel', slot: 0, frame: hostileFrame, channelId: 'missing', payload: { assetRef: 'ability.dash' } },
+        { id: 'too-soon', slot: 0, frame: hostileFrame, channelId: 'emote', payload: { assetRef: 'emote.wave' } },
+        { id: 'predicted-emote', slot: 0, frame: frames, channelId: 'emote', payload: { assetRef: 'emote.wave' }, predicted: true },
+    ];
+    timeline.setCurrentFrame(frames - 1);
+    hostile.forEach((command) => timeline.record(command));
+    const replayed = createDeterministicCommandTimeline({
+        playerCount: players,
+        currentFrame: 0,
+        channels: channelDescriptors,
+        validAssetRefs: ['ability.dash', 'ability.shield', 'emote.wave'],
+    });
+    for (const command of [...timeline.accepted].sort(compareCommandsBySubmission)) {
+        replayed.setCurrentFrame(command.submittedFrame);
+        replayed.record(command);
+    }
+    const replayedFutureCommands = replayed.accepted.filter((command) => command.submittedFrame < command.frame).length;
+    const reliableAcceptedOrder = transportMetrics.reliableOrder;
+    const replayTransport = createDeterministicCommandTransport();
+    for (const command of replayed.accepted) {
+        replayTransport.send(command, channelById.get(command.channelId), command.submittedFrame);
+    }
+    const reliableReplayedOrder = replayTransport.flush(frames + 16).reliableOrder;
+    const schemaRejected = timeline.rejected.filter((command) => command.reason === 'bad-schema').length;
+    return {
+        checksum: timeline.checksum(),
+        delivered: timeline.accepted.length,
+        rejected: timeline.rejected.length,
+        duplicateDrops,
+        multiCommandSameFrameAccepted,
+        multiCommandPollOrderStable,
+        acceptedFutureCommands,
+        replayedFutureCommands,
+        reliableDelivered,
+        reliableResent,
+        unreliableDropped,
+        reliableOrderingStable: defaultChecksum(reliableAcceptedOrder) === defaultChecksum(reliableReplayedOrder),
+        firstDeliveredFrame: timeline.accepted[0]?.frame ?? -1,
+        lastDeliveredFrame: timeline.accepted[timeline.accepted.length - 1]?.frame ?? -1,
+        delayP50Frames: percentile(delays, 50),
+        delayP95Frames: percentile(delays, 95),
+        rollbackDepthP95: percentile(rollbackDepths, 95),
+        schemaRejected,
+        schemaDeclaredPayloadsCovered: schemaRejected >= 4
+            && timeline.accepted.some((command) => command.channelId === 'ability')
+            && timeline.accepted.some((command) => command.channelId === 'emote'),
+        schemaCollectionPayloadsCovered: timeline.accepted.filter((command) => command.channelId === 'ability').some((command) => {
+            const payload = command.payload;
+            const loadout = payload.loadout;
+            return Array.isArray(payload.targets)
+                && typeof loadout === 'object'
+                && loadout !== null
+                && !Array.isArray(loadout)
+                && Array.isArray(loadout.modifiers);
+        })
+            && timeline.rejected.some((command) => command.commandId === 'bad-schema-array-length')
+            && timeline.rejected.some((command) => command.commandId === 'bad-schema-nested-array-type'),
+        convergence: defaultChecksum(timeline.accepted) === defaultChecksum(replayed.accepted),
+    };
+}
+export function runDeterministicReliableCommandDefaultsFixture(players, frames, seed) {
+    if (!Number.isInteger(players) || players < 1) {
+        throw new Error('reliable command defaults players must be at least 1');
+    }
+    if (!Number.isInteger(frames) || frames < 1) {
+        throw new Error('reliable command defaults frames must be at least 1');
+    }
+    const channels = [{
+            id: 'command',
+            reliable: true,
+            allowPrediction: true,
+            maxPayloadBytes: 128,
+            maxFrameLead: 8,
+            fields: [
+                { name: 'power', kind: 'integer', min: 0, max: 9 },
+                { name: 'target', kind: 'player-slot', min: 0, max: Math.max(0, players - 1) },
+            ],
+        }];
+    const timeline = createDeterministicCommandTimeline({
+        playerCount: players,
+        currentFrame: 0,
+        channels,
+    });
+    const transport = createDeterministicCommandTransport();
+    const acceptedCommands = [];
+    const random = new DeterministicRandom(seed + 811);
+    for (let frame = 0; frame < frames; frame += 1) {
+        timeline.setCurrentFrame(frame);
+        const burstCount = frame % 7 === 0 ? 3 : 1;
+        for (let index = 0; index < burstCount; index += 1) {
+            const slot = (frame + index + random.nextInt(0, Math.max(0, players - 1))) % players;
+            const command = {
+                id: `reliable:${frame}:${index}:${slot}`,
+                slot,
+                frame,
+                channelId: 'command',
+                payload: {
+                    power: (frame + index + seed) % 10,
+                    target: (slot + index + 1) % players,
+                },
+            };
+            timeline.record(command);
+            acceptedCommands.push({ ...command, submittedFrame: frame });
+            transport.send(command, channels[0], frame);
+        }
+    }
+    const duplicateRejected = Number(timeline.record(acceptedCommands[0])?.reason === 'duplicate-command-id');
+    timeline.setCurrentFrame(frames);
+    const staleRejected = Number(timeline.record({
+        id: 'reliable:stale',
+        slot: 0,
+        frame: Math.max(0, frames - 1),
+        channelId: 'command',
+        payload: { power: 1, target: 0 },
+    })?.reason === 'stale-frame');
+    const futureRejected = Number(timeline.record({
+        id: 'reliable:future',
+        slot: 0,
+        frame: frames + 99,
+        channelId: 'command',
+        payload: { power: 1, target: 0 },
+    })?.reason === 'future-frame');
+    const transportMetrics = transport.flush(frames + 32);
+    const replayed = createDeterministicCommandTimeline({
+        playerCount: players,
+        currentFrame: 0,
+        channels,
+    });
+    for (const command of acceptedCommands) {
+        replayed.setCurrentFrame(command.submittedFrame);
+        replayed.record(command);
+    }
+    const originalOrderHash = defaultChecksum(transportMetrics.reliableOrder);
+    const replayTransport = createDeterministicCommandTransport();
+    for (const command of replayed.accepted) {
+        replayTransport.send(command, channels[0], command.submittedFrame);
+    }
+    const replayOrderHash = defaultChecksum(replayTransport.flush(frames + 32).reliableOrder);
+    const pollOrderStable = timeline.poll(0)
+        .map((command) => command.id)
+        .join('|') === acceptedCommands.filter((command) => command.frame === 0).sort(compareCommands).map((command) => command.id).join('|');
+    const metrics = {
+        players,
+        frames,
+        accepted: acceptedCommands.length,
+        reliableDelivered: transportMetrics.reliableDelivered,
+        reliableResent: transportMetrics.reliableResent,
+        unreliableDropped: transportMetrics.unreliableDropped,
+        duplicateRejected,
+        staleRejected,
+        futureRejected,
+        pollOrderStable,
+        replayConverged: defaultChecksum(timeline.accepted) === defaultChecksum(replayed.accepted),
+        originalOrderHash,
+        replayOrderHash,
+    };
+    return { ...metrics, checksum: defaultChecksum(metrics) };
+}
+function validAbilityPayload(slot, players, assetRef, power) {
+    return {
+        assetRef,
+        power,
+        targets: [slot, (slot + 1) % Math.max(1, players)],
+        loadout: {
+            assetRef,
+            modifiers: [power % 4, (power + 1) % 4],
+        },
+    };
+}
+function createDeterministicCommandTransport() {
+    const pending = [];
+    const reliableOrder = [];
+    let reliableDelivered = 0;
+    let reliableResent = 0;
+    let unreliableDropped = 0;
+    return {
+        send(command, channel, submittedFrame) {
+            pending.push({ command, channel, attempt: 0, deliveryFrame: submittedFrame + deterministicTransportDelay(command) });
+        },
+        flush(untilFrame) {
+            const retries = [];
+            const due = pending
+                .filter((entry) => entry.deliveryFrame <= untilFrame)
+                .sort(compareTransportEntries);
+            pending.length = 0;
+            for (const entry of due) {
+                const shouldDrop = deterministicTransportDrops(entry.command, entry.attempt);
+                if (shouldDrop && entry.channel.reliable) {
+                    reliableResent += 1;
+                    retries.push({ ...entry, attempt: entry.attempt + 1, deliveryFrame: entry.deliveryFrame + 1 });
+                    continue;
+                }
+                if (shouldDrop) {
+                    unreliableDropped += 1;
+                    continue;
+                }
+                reliableDelivered += 1;
+                reliableOrder.push(entry.command.id);
+            }
+            for (const entry of retries.filter((candidate) => candidate.deliveryFrame <= untilFrame).sort(compareTransportEntries)) {
+                reliableDelivered += 1;
+                reliableOrder.push(entry.command.id);
+            }
+            return { reliableDelivered, reliableResent, unreliableDropped, reliableOrder: [...reliableOrder] };
+        },
+    };
+}
+function compareTransportEntries(left, right) {
+    return left.deliveryFrame - right.deliveryFrame || compareCommands(left.command, right.command);
+}
+function deterministicTransportDelay(command) {
+    return 1 + (stableCommandNumber(command.id) % 4);
+}
+function deterministicTransportDrops(command, attempt) {
+    const hash = stableCommandNumber(command.id);
+    if (command.channelId === 'ability') {
+        return attempt === 0 && hash % 64 === 0;
+    }
+    return attempt === 0;
+}
+function stableCommandNumber(id) {
+    let hash = 0;
+    for (let index = 0; index < id.length; index += 1) {
+        hash = (hash * 31 + id.charCodeAt(index)) % 1_000_003;
+    }
+    return hash;
+}
+function validateCommand(config, channels, validAssetRefs, commandIds, command) {
+    if (commandIds.has(command.id)) {
+        return reject(command, 'duplicate-command-id');
+    }
+    if (!Number.isInteger(command.slot) || command.slot < 0 || command.slot >= config.playerCount) {
+        return reject(command, 'unauthorized-slot');
+    }
+    if (!Number.isInteger(command.frame) || command.frame < 0) {
+        return reject(command, 'stale-frame');
+    }
+    if (command.frame < config.currentFrame) {
+        return reject(command, 'stale-frame');
+    }
+    const channel = channels.get(command.channelId);
+    if (channel === undefined) {
+        return reject(command, 'unknown-channel');
+    }
+    if (command.frame > config.currentFrame + (channel.maxFrameLead ?? 60)) {
+        return reject(command, 'future-frame');
+    }
+    if (command.frame < config.currentFrame + (channel.minFrameLead ?? 0)) {
+        return reject(command, 'insufficient-frame-lead');
+    }
+    if (command.predicted === true && channel.allowPrediction !== true) {
+        return reject(command, 'prediction-not-allowed');
+    }
+    if (canonicalStringify(command.payload).length > channel.maxPayloadBytes) {
+        return reject(command, 'oversized-payload');
+    }
+    if (channel.fields !== undefined && !deterministicPayloadMatchesFields(command.payload, channel.fields)) {
+        return reject(command, 'bad-schema');
+    }
+    if (config.validatePayload?.(command) === false) {
+        return reject(command, 'bad-schema');
+    }
+    for (const assetRef of collectCommandAssetRefs(command.payload, channel.fields)) {
+        if (validAssetRefs.size > 0 && !validAssetRefs.has(assetRef)) {
+            return reject(command, 'bad-asset-ref');
+        }
+    }
+    return undefined;
+}
+export function deterministicPayloadMatchesFields(payload, fields) {
+    try {
+        assertDeterministicPayloadFields('payload', payload, fields);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function assertDeterministicPayloadFields(label, payload, fields) {
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        throw new Error(`${label} must be a deterministic object payload`);
+    }
+    const record = payload;
+    const declared = new Map(fields.map((field) => [field.name, field]));
+    for (const field of fields) {
+        if (!Object.prototype.hasOwnProperty.call(record, field.name)) {
+            if (field.optional === true) {
+                continue;
+            }
+            throw new Error(`${label}.${field.name} is missing`);
+        }
+        assertDeterministicPayloadFieldValue(`${label}.${field.name}`, record[field.name], field);
+    }
+    for (const key of stableRecordKeys(record)) {
+        if (!declared.has(key)) {
+            throw new Error(`${label}.${key} is not declared`);
+        }
+    }
+}
+function assertDeterministicPayloadFieldValue(label, value, field) {
+    if (field.kind === 'object') {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new Error(`${label} must be object`);
+        }
+        assertDeterministicPayloadFields(label, value, field.fields ?? []);
+        return;
+    }
+    if (field.kind === 'object[]') {
+        assertDeterministicPayloadArrayLength(label, value, field);
+        for (let index = 0; index < value.length; index += 1) {
+            assertDeterministicPayloadFieldValue(`${label}[${index}]`, value[index], { ...field, kind: 'object' });
+        }
+        return;
+    }
+    if (isPayloadArrayKind(field.kind)) {
+        assertDeterministicPayloadArrayLength(label, value, field);
+        const elementKind = field.kind.slice(0, -2);
+        for (let index = 0; index < value.length; index += 1) {
+            assertDeterministicPayloadScalarFieldValue(`${label}[${index}]`, value[index], { ...field, kind: elementKind });
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        throw new Error(`${label} arrays require a declared collection schema`);
+    }
+    assertDeterministicPayloadScalarFieldValue(label, value, field);
+}
+function assertDeterministicPayloadArrayLength(label, value, field) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${label} must be array`);
+    }
+    if (field.minItems !== undefined && value.length < field.minItems) {
+        throw new Error(`${label} has fewer than ${field.minItems} items`);
+    }
+    if (field.maxItems !== undefined && value.length > field.maxItems) {
+        throw new Error(`${label} has more than ${field.maxItems} items`);
+    }
+}
+function assertDeterministicPayloadScalarFieldValue(label, value, field) {
+    switch (field.kind) {
+        case 'boolean':
+        case 'button':
+            if (typeof value !== 'boolean') {
+                throw new Error(`${label} must be boolean`);
+            }
+            return;
+        case 'string':
+        case 'asset-ref':
+            if (typeof value !== 'string') {
+                throw new Error(`${label} must be string`);
+            }
+            return;
+        case 'integer':
+        case 'fixed-q16':
+        case 'bitfield':
+        case 'player-slot':
+            if (typeof value !== 'number' || !Number.isInteger(value)) {
+                throw new Error(`${label} must be integer`);
+            }
+            if (field.min !== undefined && value < field.min) {
+                throw new Error(`${label} is below minimum ${field.min}`);
+            }
+            if (field.max !== undefined && value > field.max) {
+                throw new Error(`${label} is above maximum ${field.max}`);
+            }
+            return;
+        default:
+            throw new Error(`${label} has unknown deterministic payload kind ${field.kind}`);
+    }
+}
+function isPayloadArrayKind(kind) {
+    return kind.endsWith('[]') && kind !== 'object[]';
+}
+function validateCommandTimelineConfig(config) {
+    if (!Number.isInteger(config.playerCount) || config.playerCount < 1) {
+        throw new Error('Command timeline playerCount must be a positive integer');
+    }
+    if (!Number.isInteger(config.currentFrame) || config.currentFrame < 0) {
+        throw new Error('Command timeline currentFrame must be a non-negative integer');
+    }
+    const channelIds = new Set();
+    for (const channel of config.channels) {
+        if (channelIds.has(channel.id)) {
+            throw new Error(`Duplicate command channel id ${channel.id}`);
+        }
+        channelIds.add(channel.id);
+        if (!Number.isInteger(channel.maxPayloadBytes) || channel.maxPayloadBytes < 0) {
+            throw new Error(`Command channel ${channel.id} maxPayloadBytes must be a non-negative integer`);
+        }
+        if (channel.minFrameLead !== undefined && (!Number.isInteger(channel.minFrameLead) || channel.minFrameLead < 0)) {
+            throw new Error(`Command channel ${channel.id} minFrameLead must be a non-negative integer`);
+        }
+        if (channel.maxFrameLead !== undefined && (!Number.isInteger(channel.maxFrameLead) || channel.maxFrameLead < 0)) {
+            throw new Error(`Command channel ${channel.id} maxFrameLead must be a non-negative integer`);
+        }
+        if (channel.fields !== undefined) {
+            validateDeterministicPayloadFieldDescriptors(`channel ${channel.id}`, channel.fields);
+        }
+    }
+}
+function validateDeterministicPayloadFieldDescriptors(label, fields) {
+    const names = new Set();
+    for (const field of fields) {
+        if (names.has(field.name)) {
+            throw new Error(`${label}.${field.name} is declared more than once`);
+        }
+        names.add(field.name);
+        assertKnownDeterministicPayloadKind(`${label}.${field.name}`, field.kind);
+        if ((field.kind === 'object' || field.kind === 'object[]') && field.fields !== undefined) {
+            validateDeterministicPayloadFieldDescriptors(`${label}.${field.name}`, field.fields);
+        }
+    }
+}
+function assertKnownDeterministicPayloadKind(label, kind) {
+    if (kind === 'object' ||
+        kind === 'object[]' ||
+        kind === 'boolean' ||
+        kind === 'button' ||
+        kind === 'string' ||
+        kind === 'asset-ref' ||
+        kind === 'integer' ||
+        kind === 'fixed-q16' ||
+        kind === 'bitfield' ||
+        kind === 'player-slot' ||
+        kind === 'boolean[]' ||
+        kind === 'button[]' ||
+        kind === 'string[]' ||
+        kind === 'asset-ref[]' ||
+        kind === 'integer[]' ||
+        kind === 'fixed-q16[]' ||
+        kind === 'bitfield[]' ||
+        kind === 'player-slot[]') {
+        return;
+    }
+    throw new Error(`${label} has unknown deterministic payload kind ${kind}`);
+}
+function validateRestoredCommands(config, channels, validAssetRefs, snapshot) {
+    const restoredIds = new Set();
+    const restoredAccepted = [];
+    for (const command of snapshot.accepted) {
+        const restoredCommand = cloneCanonical(command);
+        const validation = validateCommand({ ...config, currentFrame: Math.min(snapshot.currentFrame, restoredCommand.frame) }, channels, validAssetRefs, restoredIds, restoredCommand);
+        if (validation !== undefined) {
+            throw new Error(`Invalid restored deterministic command ${restoredCommand.id}: ${validation.reason}`);
+        }
+        const submittedFrame = restoredCommand.submittedFrame ?? restoredCommand.frame;
+        if (submittedFrame > restoredCommand.frame) {
+            throw new Error(`Invalid restored deterministic command ${restoredCommand.id}: submittedFrame exceeds command frame`);
+        }
+        restoredIds.add(restoredCommand.id);
+        restoredAccepted.push({ ...restoredCommand, submittedFrame });
+    }
+    return restoredAccepted;
+}
+function collectCommandAssetRefs(value, fields) {
+    const refs = [];
+    const visitBySchema = (record, descriptors) => {
+        for (const field of descriptors) {
+            if (!Object.prototype.hasOwnProperty.call(record, field.name)) {
+                continue;
+            }
+            const child = record[field.name];
+            if (field.kind === 'asset-ref' && typeof child === 'string') {
+                refs.push(child);
+                continue;
+            }
+            if (field.kind === 'asset-ref[]' && Array.isArray(child)) {
+                for (const ref of child) {
+                    refs.push(ref);
+                }
+                continue;
+            }
+            if (field.kind === 'object') {
+                visitBySchema(child, field.fields ?? []);
+                continue;
+            }
+            if (field.kind === 'object[]' && Array.isArray(child)) {
+                for (const item of child) {
+                    visitBySchema(item, field.fields ?? []);
+                }
+            }
+        }
+    };
+    const visitByConvention = (candidate) => {
+        if (Array.isArray(candidate)) {
+            for (const item of candidate) {
+                visitByConvention(item);
+            }
+            return;
+        }
+        if (typeof candidate !== 'object' || candidate === null) {
+            return;
+        }
+        const record = candidate;
+        for (const key of stableRecordKeys(record)) {
+            const child = record[key];
+            if (key === 'assetRef' && typeof child === 'string') {
+                refs.push(child);
+            }
+            else if (key === 'assetRefs' && Array.isArray(child)) {
+                for (const ref of child) {
+                    if (typeof ref === 'string') {
+                        refs.push(ref);
+                    }
+                }
+            }
+            else {
+                visitByConvention(child);
+            }
+        }
+    };
+    if (fields === undefined) {
+        visitByConvention(value);
+    }
+    else {
+        visitBySchema(value, fields);
+    }
+    return refs.sort(compareStrings);
+}
+function stableRecordKeys(record) {
+    return Reflect.ownKeys(record)
+        .filter((key) => typeof key === 'string')
+        .sort(compareStrings);
+}
+function reject(command, reason) {
+    return { commandId: command.id, reason };
+}
+function compareCommands(left, right) {
+    return left.frame - right.frame
+        || left.slot - right.slot
+        || compareStrings(left.channelId, right.channelId)
+        || compareStrings(left.id, right.id);
+}
+function compareRejectedCommands(left, right) {
+    return compareStrings(left.commandId, right.commandId) || compareStrings(left.reason, right.reason);
+}
+function sortCommands(commands) {
+    return [...commands].sort(compareCommands);
+}
+function compareCommandsBySubmission(left, right) {
+    return left.submittedFrame - right.submittedFrame
+        || compareCommands(left, right);
+}
+function validateCommandTimelineSnapshot(snapshot) {
+    const expected = createDeterministicCommandTimelineSnapshot({
+        currentFrame: snapshot.currentFrame,
+        accepted: snapshot.accepted,
+        rejected: snapshot.rejected,
+    });
+    if (expected.checksum !== snapshot.checksum) {
+        throw new Error('Deterministic command timeline snapshot checksum mismatch');
+    }
+}
+function percentile(values, percentileRank) {
+    if (values.length === 0) {
+        return 0;
+    }
+    const sorted = [...values].sort((left, right) => left - right);
+    return sorted[Math.min(sorted.length - 1, Math.floor((percentileRank / 100) * sorted.length))];
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}