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

package/dist/replay-inspect.d.ts

@@ -0,0 +1,60 @@
+import { type CanonicalValue } from './canonical.js';
+import type { DeterministicGameDescriptor } from './schema.js';
+import type { DeterministicSessionConfig, RecordedCommandFrame, ReplayFile, RecordedInputFrame } from './types.js';
+export interface ReplayInspectConfig<State, Input> extends Omit<DeterministicSessionConfig<State, Input>, 'initialState' | 'playerCount' | 'tickRate' | 'randomSeed'> {
+    readonly replay: ReplayFile;
+}
+export interface ReplayFrameDump {
+    readonly frame: number;
+    readonly checksum: string;
+    readonly expectedChecksum?: string;
+    readonly checksumMatch?: boolean;
+    readonly inputFrame?: RecordedInputFrame;
+    readonly commandFrame?: RecordedCommandFrame;
+    readonly appliedInputFrame?: RecordedInputFrame;
+    readonly appliedCommandFrame?: RecordedCommandFrame;
+    readonly state: CanonicalValue;
+    readonly checksumExplanation?: ReplayChecksumExplanation;
+}
+export interface ReplayFrameDiff {
+    readonly path: string;
+    readonly left: CanonicalValue | undefined;
+    readonly right: CanonicalValue | undefined;
+}
+export interface ReplayDiffResult {
+    readonly frame: number;
+    readonly leftChecksum: string;
+    readonly rightChecksum: string;
+    readonly checksumMatch: boolean;
+    readonly differences: readonly ReplayFrameDiff[];
+}
+export interface ReplayChecksumExplanation {
+    readonly frame: number;
+    readonly checksum: string;
+    readonly tableCount: number;
+    readonly tables: readonly ReplayChecksumTableExplanation[];
+}
+export interface ReplayChecksumTableExplanation {
+    readonly path: string;
+    readonly checksum: string;
+    readonly bytes: number;
+    readonly entries: number;
+    readonly sampleKeys: readonly string[];
+}
+export interface DescriptorReplayInspectConfig<State, Input> {
+    readonly descriptor: DeterministicGameDescriptor;
+    readonly replay: ReplayFile;
+    readonly step: DeterministicSessionConfig<State, Input>['step'];
+    readonly defaultInput: Input;
+    readonly hydrateInput?: (recordedInput: unknown) => Input;
+}
+export declare function inspectReplayFrame<State, Input>(config: ReplayInspectConfig<State, Input>, frame: number, options?: {
+    readonly explainChecksum?: boolean;
+}): ReplayFrameDump;
+export declare function inspectReplayFrameWithDescriptor<State, Input>(config: DescriptorReplayInspectConfig<State, Input>, frame: number, options?: {
+    readonly explainChecksum?: boolean;
+}): ReplayFrameDump;
+export declare function explainReplayChecksum(dump: Pick<ReplayFrameDump, 'frame' | 'checksum' | 'state'>): ReplayChecksumExplanation;
+export declare function diffReplayFrames(left: ReplayFrameDump, right: ReplayFrameDump, maxDifferences?: number): ReplayDiffResult;
+export declare function stableFrameDumpJson(dump: ReplayFrameDump): string;
+export declare function stableFrameDiffJson(diff: ReplayDiffResult): string;

package/dist/replay-inspect.js

@@ -0,0 +1,228 @@
+import { canonicalize, cloneCanonical, decodeCanonicalValue, defaultChecksum, encodeUtf8 } from './canonical.js';
+import { stableSortedKeys } from './collections.js';
+import { SyncplayError } from './errors.js';
+import { createOfflineSession } from './offline-session.js';
+import { assertReplayFileStructure } from './replay.js';
+import { createSchemaArtifacts } from './schema-artifacts.js';
+export function inspectReplayFrame(config, frame, options = {}) {
+    assertReplayFileStructure(config.replay);
+    validateFrame(config.replay, frame);
+    assertReplayIdentity(config);
+    const initialState = decodeCanonicalValue(config.replay.initialState);
+    const session = createOfflineSession({
+        ...config,
+        initialState,
+        playerCount: config.replay.playerCount,
+        tickRate: config.replay.tickRate,
+        randomSeed: config.replay.randomSeed,
+        replayRecordingMode: 'none',
+        snapshotBufferSize: Math.max(1, frame + 1),
+    });
+    const commandFrames = new Map((config.replay.commandHistory ?? []).map((commandFrame) => [commandFrame.frame, commandFrame.commands]));
+    for (const inputFrame of config.replay.inputFrames) {
+        if (inputFrame.frame >= frame) {
+            break;
+        }
+        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 state = config.canonicalizeState?.(session.getState()) ?? session.getState();
+    const checksum = String(config.checksum?.(session.getState()) ?? defaultChecksum(state));
+    const expectedChecksum = replayChecksumForFrame(config.replay, frame);
+    const dump = {
+        frame,
+        checksum,
+        expectedChecksum,
+        checksumMatch: expectedChecksum === undefined ? undefined : expectedChecksum === checksum,
+        inputFrame: cloneOptional(config.replay.inputFrames.find((record) => record.frame === frame)),
+        commandFrame: cloneOptional(config.replay.commandHistory?.find((record) => record.frame === frame)),
+        appliedInputFrame: cloneOptional(config.replay.inputFrames.find((record) => record.frame === frame - 1)),
+        appliedCommandFrame: cloneOptional(config.replay.commandHistory?.find((record) => record.frame === frame - 1)),
+        state: canonicalize(state),
+    };
+    return {
+        ...dump,
+        checksumExplanation: options.explainChecksum === true ? explainReplayChecksum(dump) : undefined,
+    };
+}
+export function inspectReplayFrameWithDescriptor(config, frame, options = {}) {
+    const artifacts = createSchemaArtifacts(config.descriptor);
+    return inspectReplayFrame({
+        replay: config.replay,
+        step: config.step,
+        defaultInput: config.defaultInput,
+        // The content-hashed identity, matching what runtimes stamp into exported
+        // replays — same contract as verifyReplayWithDescriptor.
+        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,
+    }, frame, options);
+}
+export function explainReplayChecksum(dump) {
+    const state = dump.state;
+    const tables = isRecord(state)
+        ? stableSortedKeys(state)
+            .map((key) => explainChecksumTable(`state.${key}`, state[key]))
+        : [explainChecksumTable('state', state)];
+    return {
+        frame: dump.frame,
+        checksum: dump.checksum,
+        tableCount: tables.length,
+        tables,
+    };
+}
+export function diffReplayFrames(left, right, maxDifferences = 200) {
+    const differences = [];
+    collectDiffs('state', left.state, right.state, differences, maxDifferences);
+    return {
+        frame: left.frame,
+        leftChecksum: left.checksum,
+        rightChecksum: right.checksum,
+        checksumMatch: left.checksum === right.checksum,
+        differences,
+    };
+}
+export function stableFrameDumpJson(dump) {
+    return `${JSON.stringify(dump)}\n`;
+}
+export function stableFrameDiffJson(diff) {
+    return `${JSON.stringify(diff)}\n`;
+}
+function collectDiffs(path, left, right, differences, maxDifferences) {
+    if (differences.length >= maxDifferences || stringifyCanonicalForDiff(left) === stringifyCanonicalForDiff(right)) {
+        return;
+    }
+    if (Array.isArray(left) && Array.isArray(right)) {
+        const length = Math.max(left.length, right.length);
+        for (let index = 0; index < length; index += 1) {
+            collectDiffs(`${path}[${index}]`, left[index], right[index], differences, maxDifferences);
+            if (differences.length >= maxDifferences) {
+                return;
+            }
+        }
+        return;
+    }
+    if (!isRecord(left) || !isRecord(right)) {
+        differences.push({ path, left, right });
+        return;
+    }
+    const keys = mergeStableKeys(left, right);
+    for (const key of keys) {
+        collectDiffs(`${path}.${key}`, left[key], right[key], differences, maxDifferences);
+        if (differences.length >= maxDifferences) {
+            return;
+        }
+    }
+}
+function isRecord(value) {
+    return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function stringifyCanonicalForDiff(value) {
+    return value === undefined ? '<undefined>' : JSON.stringify(value);
+}
+function explainChecksumTable(path, value) {
+    const source = JSON.stringify(value);
+    return {
+        path,
+        checksum: defaultChecksum(source),
+        bytes: encodeUtf8(source).byteLength,
+        entries: countEntries(value),
+        sampleKeys: sampleKeys(value),
+    };
+}
+function countEntries(value) {
+    if (Array.isArray(value)) {
+        return value.length;
+    }
+    if (isRecord(value)) {
+        return stableSortedKeys(value).length;
+    }
+    return 1;
+}
+function sampleKeys(value) {
+    if (Array.isArray(value)) {
+        return value.slice(0, 5).map((_, index) => `[${index}]`);
+    }
+    if (isRecord(value)) {
+        return stableSortedKeys(value).slice(0, 5);
+    }
+    return [];
+}
+function validateFrame(replay, frame) {
+    if (!Number.isInteger(frame) || frame < 0 || frame > replay.inputFrames.length) {
+        throw new SyncplayError(`Replay frame ${frame} is outside 0..${replay.inputFrames.length}`, {
+            code: 'replay.inspect-frame',
+            frame,
+        });
+    }
+}
+function mergeStableKeys(left, right) {
+    return [...new Set([...stableSortedKeys(left), ...stableSortedKeys(right)])].sort(compareStrings);
+}
+function compareStrings(left, right) {
+    return Number(left > right) - Number(left < right);
+}
+function assertReplayIdentity(config) {
+    const checks = [
+        ['deterministicVersion', config.deterministicVersion, config.replay.deterministicVersion],
+        ['inputSchemaId', config.inputSchemaId, config.replay.inputSchemaId],
+        ['stateSchemaId', config.stateSchemaId, config.replay.stateSchemaId],
+        ['engineIdentityHash', config.engineIdentityHash, config.replay.engineIdentityHash],
+        ['assetDbHash', config.assetDbHash, config.replay.assetDbHash],
+        ['configHash', config.configHash, config.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 replayChecksumForFrame(replay, frame) {
+    const checksums = replay.checksums.filter((record) => record.frame === frame);
+    if (checksums.length > 1) {
+        throw new SyncplayError(`Replay frame ${frame} has duplicate checksum records`, {
+            code: 'replay.inspect-checksum',
+            frame,
+        });
+    }
+    return checksums[0]?.checksum;
+}
+function cloneOptional(value) {
+    return value === undefined ? undefined : cloneCanonical(value);
+}

package/dist/replay-scoring.d.ts

@@ -0,0 +1,28 @@
+import { type ReplayVerificationConfig } from './replay.js';
+/**
+ * Replay-verified score submission (M8.5): re-simulate a submitted
+ * {@link ReplayFile} and check that the game's own score extraction over the
+ * FINAL state matches the score the client claimed. A tampered score fails the
+ * extraction check; tampered inputs/state fail the recorded-checksum
+ * re-simulation. The verifier needs the game's deterministic config (step,
+ * schemas) — hosting that server-side is the submission pipeline's problem;
+ * this is the game-agnostic core it calls.
+ */
+export interface ScoredReplayVerificationConfig<State, Input> extends ReplayVerificationConfig<State, Input> {
+    readonly submittedScore: number;
+    /** Game-supplied: read the canonical score out of the final state. */
+    readonly extractScore: (finalState: State) => number;
+}
+export type ScoredReplayRejection = 'replay-mismatch' | 'score-mismatch';
+export interface ScoredReplayVerdict {
+    readonly ok: boolean;
+    readonly reason?: ScoredReplayRejection;
+    readonly replayScore?: number;
+    readonly submittedScore: number;
+    readonly frames: number;
+    readonly verifiedChecksums: number;
+    readonly finalChecksum: string;
+    /** First mismatching frame when reason is 'replay-mismatch'. */
+    readonly mismatchFrame?: number;
+}
+export declare function verifyScoredReplay<State, Input>(config: ScoredReplayVerificationConfig<State, Input>): ScoredReplayVerdict;

package/dist/replay-scoring.js

@@ -0,0 +1,65 @@
+import { decodeCanonicalValue } from './canonical.js';
+import { createOfflineSession } from './offline-session.js';
+import { verifyReplay } from './replay.js';
+export function verifyScoredReplay(config) {
+    const { submittedScore, extractScore, ...verification } = config;
+    const result = verifyReplay({ ...verification, throwOnMismatch: false });
+    if (result.mismatches > 0) {
+        return {
+            ok: false,
+            reason: 'replay-mismatch',
+            submittedScore,
+            frames: result.frames,
+            verifiedChecksums: result.checksums,
+            finalChecksum: result.finalChecksum,
+            ...(result.firstMismatch === undefined ? {} : { mismatchFrame: result.firstMismatch.frame }),
+        };
+    }
+    // The replay re-simulated clean — walk it once more to materialize the final
+    // state for score extraction (verifyReplay reports checksums, not state).
+    const replay = config.replay;
+    const session = createOfflineSession({
+        ...verification,
+        initialState: decodeCanonicalValue(replay.initialState),
+        playerCount: replay.playerCount,
+        tickRate: replay.tickRate,
+        randomSeed: replay.randomSeed,
+    });
+    const commandFrames = new Map((replay.commandHistory ?? []).map((frame) => [frame.frame, frame.commands]));
+    for (const inputFrame of replay.inputFrames) {
+        inputFrame.inputs.forEach((input, slot) => {
+            const decoded = decodeCanonicalValue(input);
+            const flags = inputFrame.inputFlags?.[slot];
+            const replayInput = flags?.playerPresent === false ? config.defaultInput : (config.hydrateInput?.(decoded) ?? decoded);
+            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 replayScore = extractScore(session.getState());
+    if (replayScore !== submittedScore) {
+        return {
+            ok: false,
+            reason: 'score-mismatch',
+            replayScore,
+            submittedScore,
+            frames: result.frames,
+            verifiedChecksums: result.checksums,
+            finalChecksum: result.finalChecksum,
+        };
+    }
+    return {
+        ok: true,
+        replayScore,
+        submittedScore,
+        frames: result.frames,
+        verifiedChecksums: result.checksums,
+        finalChecksum: result.finalChecksum,
+    };
+}

package/dist/replay.d.ts

@@ -0,0 +1,17 @@
+import type { DeterministicGameDescriptor } from './schema.js';
+import type { DeterministicSessionConfig, ReplayFile, ReplayVerificationResult } from './types.js';
+export interface ReplayVerificationConfig<State, Input> extends Omit<DeterministicSessionConfig<State, Input>, 'initialState' | 'playerCount' | 'tickRate' | 'randomSeed'> {
+    readonly replay: ReplayFile;
+    readonly throwOnMismatch?: boolean;
+}
+export interface DescriptorReplayVerificationConfig<State, Input> {
+    readonly descriptor: DeterministicGameDescriptor;
+    readonly replay: ReplayFile;
+    readonly step: DeterministicSessionConfig<State, Input>['step'];
+    readonly defaultInput: Input;
+    readonly hydrateInput?: (recordedInput: unknown) => Input;
+    readonly throwOnMismatch?: boolean;
+}
+export declare function verifyReplay<State, Input>(config: ReplayVerificationConfig<State, Input>): ReplayVerificationResult;
+export declare function verifyReplayWithDescriptor<State, Input>(config: DescriptorReplayVerificationConfig<State, Input>): ReplayVerificationResult;
+export declare function assertReplayFileStructure(replay: ReplayFile): void;