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

package/dist/replay.js

@@ -0,0 +1,351 @@
+import { canonicalize, canonicalStringify, decodeCanonicalValue, defaultChecksum } from './canonical.js';
+import { SyncplayError } from './errors.js';
+import { createOfflineSession } from './offline-session.js';
+import { createSchemaArtifacts } from './schema-artifacts.js';
+export function verifyReplay(config) {
+    const replay = config.replay;
+    assertReplayFileStructure(replay);
+    assertReplayIdentity(config);
+    const initialState = decodeCanonicalValue(replay.initialState);
+    const session = createOfflineSession({
+        ...config,
+        initialState,
+        playerCount: replay.playerCount,
+        tickRate: replay.tickRate,
+        randomSeed: replay.randomSeed,
+    });
+    const checksums = new Map(replay.checksums.map((checksum) => [checksum.frame, checksum.checksum]));
+    const commandFrames = new Map((replay.commandHistory ?? []).map((commandFrame) => [commandFrame.frame, commandFrame.commands]));
+    let verifiedChecksums = 0;
+    let finalChecksum = String(defaultChecksum(initialState));
+    for (const inputFrame of replay.inputFrames) {
+        if (inputFrame.frame !== session.currentFrame) {
+            throw new SyncplayError(`Replay input frame ${inputFrame.frame} does not match session frame ${session.currentFrame}`, { code: 'replay.input-frame-gap', frame: session.currentFrame });
+        }
+        inputFrame.inputs.forEach((input, slot) => {
+            const decodedInput = decodeCanonicalValue(input);
+            const flags = inputFrame.inputFlags?.[slot];
+            const replayInput = flags?.playerPresent === false ? config.defaultInput : (config.hydrateInput?.(decodedInput) ?? decodedInput);
+            session.setInput(slot, replayInput);
+            if (flags !== undefined) {
+                session.setInputFlags(slot, flags);
+            }
+        });
+        const commands = commandFrames.get(inputFrame.frame);
+        if (commands !== undefined) {
+            session.recordCommands(commands.map((command) => decodeCanonicalValue(command)));
+        }
+        session.stepFrames(1);
+        const expectedChecksum = checksums.get(session.currentFrame);
+        if (expectedChecksum !== undefined) {
+            const actualChecksum = String(config.checksum?.(session.getState()) ?? defaultChecksum(config.canonicalizeState?.(session.getState()) ?? session.getState()));
+            verifiedChecksums += 1;
+            finalChecksum = actualChecksum;
+            if (actualChecksum !== expectedChecksum) {
+                const mismatch = {
+                    frame: session.currentFrame,
+                    expectedChecksum,
+                    actualChecksum,
+                    inputFrame,
+                    state: canonicalize(config.canonicalizeState?.(session.getState()) ?? session.getState()),
+                };
+                if (config.throwOnMismatch === false) {
+                    return {
+                        frames: session.currentFrame,
+                        checksums: verifiedChecksums,
+                        mismatches: 1,
+                        finalChecksum,
+                        firstMismatch: mismatch,
+                    };
+                }
+                throw new SyncplayError(`Checksum mismatch at frame ${session.currentFrame}: expected ${expectedChecksum}, actual ${actualChecksum}`, { code: 'replay.checksum-mismatch', frame: session.currentFrame });
+            }
+        }
+    }
+    if (verifiedChecksums !== replay.checksums.length) {
+        throw new SyncplayError(`Replay contained ${replay.checksums.length - verifiedChecksums} checksum records beyond verified input frames`, { code: 'replay.unverified-checksum', frame: session.currentFrame });
+    }
+    return {
+        frames: session.currentFrame,
+        checksums: verifiedChecksums,
+        mismatches: 0,
+        finalChecksum,
+    };
+}
+export function verifyReplayWithDescriptor(config) {
+    const artifacts = createSchemaArtifacts(config.descriptor);
+    return verifyReplay({
+        replay: config.replay,
+        step: config.step,
+        defaultInput: config.defaultInput,
+        // The CONTENT-HASHED identity, not the author label: runtimes stamp
+        // replayIdentity.* into exported replays (a field edit without a label
+        // bump must change the identity), so the descriptor-derived verifier must
+        // compare the same form or every defineSyncplayGame replay fails identity.
+        inputSchemaId: artifacts.descriptor.replayIdentity.inputSchemaId,
+        stateSchemaId: artifacts.descriptor.replayIdentity.stateSchemaId,
+        deterministicVersion: artifacts.descriptor.deterministicVersion,
+        canonicalizeInput(input) {
+            return artifacts.canonicalizeInput(input);
+        },
+        canonicalizeState(state) {
+            return artifacts.canonicalizeState(state);
+        },
+        checksum(state) {
+            return artifacts.checksumState(state);
+        },
+        serializeState(state) {
+            return artifacts.serializeState(state);
+        },
+        deserializeState(bytes) {
+            return artifacts.deserializeState(bytes);
+        },
+        hydrateInput: config.hydrateInput,
+        throwOnMismatch: config.throwOnMismatch,
+    });
+}
+export function assertReplayFileStructure(replay) {
+    if (replay.formatVersion !== 1) {
+        throw new SyncplayError(`Unsupported replay format ${replay.formatVersion}`, {
+            code: 'replay.format-version',
+        });
+    }
+    assertReplayCanonicalValue(replay.initialState, 'Replay initialState is not a valid canonical value', {});
+    for (const inputFrame of replay.inputFrames) {
+        if (inputFrame.inputs.length !== replay.playerCount) {
+            throw new SyncplayError(`Replay frame ${inputFrame.frame} has ${inputFrame.inputs.length} inputs, expected ${replay.playerCount}`, {
+                code: 'replay.input-count',
+                frame: inputFrame.frame,
+            });
+        }
+        validateInputFlags(replay, inputFrame);
+        inputFrame.inputs.forEach((input, slot) => assertReplayCanonicalValue(input, `Replay frame ${inputFrame.frame} input ${slot} is not a valid canonical value`, { frame: inputFrame.frame, slot }));
+    }
+    for (const commandFrame of replay.commandHistory ?? []) {
+        if (!Number.isInteger(commandFrame.frame) || commandFrame.frame < 0 || commandFrame.frame >= replay.inputFrames.length) {
+            throw new SyncplayError(`Replay command frame ${commandFrame.frame} is outside replay input history`, {
+                code: 'replay.command-frame-gap',
+                frame: commandFrame.frame,
+            });
+        }
+        for (const command of commandFrame.commands) {
+            const canonicalCommand = command;
+            assertReplayCanonicalValue(canonicalCommand, `Replay command frame ${commandFrame.frame} contains a non-canonical command`, { frame: commandFrame.frame });
+        }
+    }
+}
+function assertReplayIdentity(config) {
+    const replay = config.replay;
+    const checks = [
+        ['deterministicVersion', config.deterministicVersion, replay.deterministicVersion],
+        ['inputSchemaId', config.inputSchemaId, replay.inputSchemaId],
+        ['stateSchemaId', config.stateSchemaId, replay.stateSchemaId],
+        ['engineIdentityHash', config.engineIdentityHash, replay.engineIdentityHash],
+        ['assetDbHash', config.assetDbHash, replay.assetDbHash],
+        ['configHash', config.configHash, replay.configHash],
+    ];
+    for (const [field, actual, expected] of checks) {
+        if (actual === undefined || expected === undefined) {
+            continue;
+        }
+        if (actual !== expected) {
+            throw new SyncplayError(`Replay ${field} mismatch: expected ${expected}, actual ${actual}`, {
+                code: 'replay.identity-mismatch',
+            });
+        }
+    }
+}
+function validateInputFlags(replay, inputFrame) {
+    if (inputFrame.inputFlags === undefined) {
+        return;
+    }
+    if (inputFrame.inputFlags.length !== replay.playerCount) {
+        throw new SyncplayError(`Replay frame ${inputFrame.frame} has ${inputFrame.inputFlags.length} input flag records, expected ${replay.playerCount}`, {
+            code: 'replay.input-flag-count',
+            frame: inputFrame.frame,
+        });
+    }
+    const commandSlots = new Set();
+    for (const commandFrame of replay.commandHistory ?? []) {
+        if (commandFrame.frame !== inputFrame.frame) {
+            continue;
+        }
+        for (const command of commandFrame.commands) {
+            if (!isCanonicalReplayValue(command)) {
+                continue;
+            }
+            let decoded;
+            try {
+                decoded = decodeCanonicalValue(command);
+            }
+            catch {
+                continue;
+            }
+            if (isRecord(decoded) && typeof decoded.slot === 'number') {
+                commandSlots.add(decoded.slot);
+            }
+        }
+    }
+    inputFrame.inputFlags.forEach((flags, slot) => {
+        if (flags.slot !== slot) {
+            throw new SyncplayError(`Replay frame ${inputFrame.frame} input flags slot ${flags.slot} do not match index ${slot}`, {
+                code: 'replay.input-flag-slot',
+                frame: inputFrame.frame,
+                slot,
+            });
+        }
+        if (flags.playerPresent !== true && flags.playerPresent !== false) {
+            throw new SyncplayError(`Replay frame ${inputFrame.frame} input flags for slot ${slot} have invalid playerPresent`, {
+                code: 'replay.input-flag-value',
+                frame: inputFrame.frame,
+                slot,
+            });
+        }
+        if (flags.playerPresent === false && flags.replacedByServer === true) {
+            throw new SyncplayError(`Replay frame ${inputFrame.frame} input flags for slot ${slot} cannot be absent and server-replaced`, {
+                code: 'replay.input-flag-conflict',
+                frame: inputFrame.frame,
+                slot,
+            });
+        }
+        if (flags.commandInput !== commandSlots.has(slot)) {
+            throw new SyncplayError(`Replay frame ${inputFrame.frame} input command flag for slot ${slot} does not match command history`, {
+                code: 'replay.input-flag-command',
+                frame: inputFrame.frame,
+                slot,
+            });
+        }
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertReplayCanonicalValue(value, message, options) {
+    try {
+        if (!isCanonicalReplayValue(value)) {
+            throw new Error('not canonical');
+        }
+        decodeCanonicalValue(value);
+    }
+    catch {
+        throw new SyncplayError(message, {
+            code: 'replay.canonical-value',
+            frame: options.frame,
+            slot: options.slot,
+        });
+    }
+}
+function isCanonicalReplayValue(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string') {
+        return true;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) && !Object.is(value, -0);
+    }
+    if (Array.isArray(value)) {
+        return value.every((item) => isCanonicalReplayValue(item));
+    }
+    if (!isRecord(value) || Object.getPrototypeOf(value) !== Object.prototype) {
+        return false;
+    }
+    if (Object.prototype.hasOwnProperty.call(value, '$rdm')) {
+        return isCanonicalReplayTag(value);
+    }
+    if (!replayObjectKeysAreCanonical(value)) {
+        return false;
+    }
+    return replayObjectKeys(value).every((key) => isCanonicalReplayValue(value[key]));
+}
+function isCanonicalReplayTag(value) {
+    const tag = value.$rdm;
+    if (typeof tag !== 'string') {
+        return false;
+    }
+    switch (tag) {
+        case 'nan':
+        case 'infinity':
+        case 'negative-infinity':
+        case 'negative-zero':
+        case 'undefined':
+            return hasExactReplayTagKeys(value, ['$rdm']);
+        case 'bigint':
+            return hasExactReplayTagKeys(value, ['$rdm', 'value']) && typeof value.value === 'string';
+        case 'map':
+            return hasExactReplayTagKeys(value, ['$rdm', 'entries']) &&
+                Array.isArray(value.entries) &&
+                value.entries.every((entry) => Array.isArray(entry) &&
+                    entry.length === 2 &&
+                    isCanonicalReplayValue(entry[0]) &&
+                    isCanonicalReplayValue(entry[1])) &&
+                replayMapEntriesAreCanonical(value.entries);
+        case 'set':
+            return hasExactReplayTagKeys(value, ['$rdm', 'values']) &&
+                Array.isArray(value.values) &&
+                value.values.every((entry) => isCanonicalReplayValue(entry)) &&
+                replaySetValuesAreCanonical(value.values);
+        case 'typed-array':
+            return hasExactReplayTagKeys(value, ['$rdm', 'constructor', 'bytes']) &&
+                typeof value.constructor === 'string' &&
+                Array.isArray(value.bytes) &&
+                value.bytes.every((byte) => Number.isInteger(byte) && byte >= 0 && byte <= 255);
+        default:
+            return false;
+    }
+}
+function hasExactReplayTagKeys(value, expectedKeys) {
+    const actual = replayObjectKeys(value);
+    if (actual.length !== expectedKeys.length) {
+        return false;
+    }
+    return actual.every((key, index) => key === expectedKeys[index]);
+}
+function replayObjectKeysAreCanonical(value) {
+    const actual = replayObjectKeys(value);
+    const expected = [...actual].sort(compareStrings);
+    return actual.every((key, index) => key === expected[index]);
+}
+function replayObjectKeys(value) {
+    // rdm-ignore-next-line determinism/no-object-key-order: replay canonical validation intentionally reads encoded object key order before comparing it to canonical order
+    return Object.keys(value);
+}
+function replayMapEntriesAreCanonical(entries) {
+    let previousKeyText;
+    for (const entry of entries) {
+        const key = entry[0];
+        const keyText = canonicalReplaySortText(key);
+        if (keyText === undefined) {
+            return false;
+        }
+        if (previousKeyText !== undefined && previousKeyText > keyText) {
+            return false;
+        }
+        previousKeyText = keyText;
+    }
+    return true;
+}
+function replaySetValuesAreCanonical(values) {
+    let previousValueText;
+    for (const value of values) {
+        const canonicalValue = value;
+        const valueText = canonicalReplaySortText(canonicalValue);
+        if (valueText === undefined) {
+            return false;
+        }
+        if (previousValueText !== undefined && previousValueText > valueText) {
+            return false;
+        }
+        previousValueText = valueText;
+    }
+    return true;
+}
+function canonicalReplaySortText(value) {
+    try {
+        return canonicalStringify(decodeCanonicalValue(value));
+    }
+    catch {
+        return undefined;
+    }
+}
+function compareStrings(left, right) {
+    return Number(left > right) - Number(left < right);
+}

package/dist/reports.d.ts

@@ -0,0 +1,176 @@
+import type { DeterministicAssetCookManifest } from './asset-cooking.js';
+import type { ProtocolRollbackLabOptions, ProtocolRollbackLabResult } from './protocol-lab.js';
+import type { DeterminismDiagnostic, DeterminismParserKind, DeterminismSuppression } from './tools/static-checker.js';
+import type { ReplayVerificationMismatch, TickRate } from './types.js';
+export interface DeterministicReport<Config, Metrics> {
+    readonly schemaVersion: 1;
+    readonly reportId: string;
+    readonly kind: string;
+    readonly generatedAtFrame: number;
+    readonly config: Config;
+    readonly metrics: Metrics;
+    readonly result: 'pass' | 'fail' | 'desync' | 'warn';
+}
+export type ProtocolRollbackReport = DeterministicReport<{
+    readonly game: string;
+    readonly players: number;
+    readonly frames: number;
+    readonly seed: number;
+    readonly minDelayFrames: number;
+    readonly maxDelayFrames: number;
+    readonly bundleSizeFrames: number;
+    readonly inputDelayFrames: number;
+    readonly duplicatePermille: number;
+    readonly lossPermille: number;
+    readonly resendIntervalFrames: number;
+    readonly maxResendAttempts: number;
+    readonly disconnectStartFrame?: number;
+    readonly disconnectEndFrame?: number;
+    readonly lateJoinSlot?: number;
+    readonly lateJoinFrame?: number;
+    readonly latencySkewSlot?: number;
+    readonly latencySkewFrames?: number;
+    readonly botSlots: readonly number[];
+    readonly desyncFrame?: number;
+    readonly desyncSlot?: number;
+    readonly expectDesync: boolean;
+    readonly eventTimelineLimit: number;
+    readonly predictionPolicy: string;
+}, ProtocolRollbackLabResult & {
+    readonly elapsedMs: string;
+    readonly heapUsedBytes: number;
+    readonly rssBytes: number;
+}>;
+export interface DeterministicReportDiffEntry {
+    readonly path: string;
+    readonly left: string;
+    readonly right: string;
+}
+export interface DeterministicReportDiff {
+    readonly schemaVersion: 1;
+    readonly kind: 'report-diff';
+    readonly leftReportId: string;
+    readonly rightReportId: string;
+    readonly differences: number;
+    readonly truncatedDifferences: number;
+    readonly entries: readonly DeterministicReportDiffEntry[];
+    readonly result: 'pass' | 'diff';
+}
+export interface DeterministicAssetCookCliFileResult {
+    readonly path: string;
+    readonly expected: 'pass' | 'fail';
+    readonly actual: 'pass' | 'fail';
+    readonly assetDbHash?: string;
+    readonly schemaHash?: string;
+    readonly dependencyHash?: string;
+    readonly lookupHash?: string;
+    readonly assetCount?: number;
+    readonly byteStable?: boolean;
+    readonly lookupStable?: boolean;
+    readonly schemaHashStable?: boolean;
+    readonly dependencyOrderStable?: boolean;
+    readonly prototypeSpawned?: boolean;
+    readonly staleEngineRejected?: boolean;
+    readonly staleAssetDbRejected?: boolean;
+    readonly manifest?: DeterministicAssetCookManifest;
+    readonly error?: string;
+}
+export interface DeterministicAssetCookCliReport {
+    readonly schemaVersion: 1;
+    readonly kind: 'deterministic-asset-cook';
+    readonly files: number;
+    readonly cookedAssets: number;
+    readonly combinedHash: string;
+    readonly results: readonly DeterministicAssetCookCliFileResult[];
+    readonly result: 'pass' | 'fail';
+}
+export interface ReplayVerifyCliFileResult {
+    readonly path: string;
+    readonly frames: number;
+    readonly players: number;
+    readonly tickRate: TickRate;
+    readonly checksums: number;
+    readonly mismatches: number;
+    readonly finalChecksum: string;
+    readonly firstMismatch?: ReplayVerificationMismatch;
+    readonly result: 'pass' | 'fail';
+}
+export interface ReplayVerifyCliReport {
+    readonly schemaVersion: 1;
+    readonly kind: 'replay-verify';
+    readonly files: number;
+    readonly startFrame: number;
+    readonly endFrame: number | '';
+    readonly frames: number;
+    readonly checksums: number;
+    readonly mismatches: number;
+    readonly results: readonly ReplayVerifyCliFileResult[];
+    readonly firstMismatch?: ReplayVerificationMismatch;
+    readonly heapUsedBytes: number;
+    readonly rssBytes: number;
+    readonly elapsedMs: string;
+    readonly result: 'pass' | 'fail';
+}
+export interface StaticDeterminismReport {
+    readonly schemaVersion: 1;
+    readonly kind: 'static-determinism';
+    readonly parser: DeterminismParserKind;
+    readonly certificationMode: boolean;
+    readonly sourceOnly: boolean;
+    readonly checkedPaths: readonly string[];
+    readonly project?: string;
+    readonly classifiedExcludedPaths?: readonly string[];
+    readonly boundaryCheckedPaths?: readonly string[];
+    readonly knownBadPaths: readonly string[];
+    readonly diagnostics: readonly DeterminismDiagnostic[];
+    readonly boundaryDiagnostics?: readonly DeterminismDiagnostic[];
+    readonly knownBadDiagnostics: readonly DeterminismDiagnostic[];
+    readonly passErrors: number;
+    readonly boundaryErrors?: number;
+    readonly knownBadErrors: number;
+    readonly suppressions: readonly DeterminismSuppression[];
+    readonly suppressionCount: number;
+    readonly invalidSuppressions: number;
+    readonly engineCompleteAudit?: StaticDeterminismEngineCompleteArtifactAudit;
+    readonly engineParityAudit?: StaticDeterminismEngineParityArtifactAudit;
+    readonly result: 'pass' | 'fail';
+}
+export interface StaticDeterminismEngineCompleteArtifactAudit {
+    readonly checked: boolean;
+    readonly result: 'pass' | 'warn' | 'fail';
+    readonly reports: readonly StaticDeterminismEngineCompleteArtifactAuditReport[];
+    readonly warnings: readonly string[];
+    readonly failures: readonly string[];
+}
+export interface StaticDeterminismEngineCompleteArtifactAuditReport {
+    readonly path: string;
+    readonly kind: 'certification' | 'benchmark';
+    readonly result: 'pass' | 'fail' | 'missing' | 'invalid';
+    readonly categories: readonly StaticDeterminismEngineCompleteArtifactAuditCategory[];
+    readonly warnings: readonly string[];
+    readonly failures: readonly string[];
+}
+export interface StaticDeterminismEngineCompleteArtifactAuditCategory {
+    readonly category: string;
+    readonly result: 'pass' | 'fail';
+    readonly requestedFrames: number;
+    readonly executedFrames: number;
+    readonly capped: boolean;
+    readonly wallClockElapsedMs: number;
+    readonly wallClockMeanFrameMs: number;
+}
+export interface StaticDeterminismEngineParityArtifactAudit {
+    readonly checked: boolean;
+    readonly result: 'pass' | 'fail';
+    readonly files: readonly string[];
+    readonly failures: readonly string[];
+}
+export declare function createProtocolRollbackReport(options: ProtocolRollbackLabOptions, result: ProtocolRollbackLabResult & {
+    readonly elapsedMs: string;
+    readonly heapUsedBytes: number;
+    readonly rssBytes: number;
+}): ProtocolRollbackReport;
+export declare function stableReportJson(report: DeterministicReport<unknown, unknown>): string;
+export declare function diffDeterministicReports(left: unknown, right: unknown, maxDifferences?: number): DeterministicReportDiff;
+export declare function stableReportDiffJson(diff: DeterministicReportDiff): string;
+export declare function renderDeterministicReportHtml(report: DeterministicReport<unknown, unknown>): string;