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

package/dist/r3f-render-adapter.d.ts

@@ -0,0 +1,61 @@
+import type { DeterministicOfflineRuntime } from './sdk-offline.js';
+export type DeterministicRenderReadonly<T> = T extends (...args: readonly never[]) => unknown ? never : T extends readonly (infer Item)[] ? readonly DeterministicRenderReadonly<Item>[] : T extends object ? {
+    readonly [Key in keyof T]: DeterministicRenderReadonly<T[Key]>;
+} : T;
+export interface DeterministicR3fRenderFrame<RenderState> {
+    readonly mode: 'offline';
+    readonly frame: number;
+    readonly predictedFrame: number;
+    readonly verifiedFrame: number;
+    readonly checksum: string;
+    readonly debug: DeterministicR3fRenderDebug;
+    readonly state: DeterministicRenderReadonly<RenderState>;
+}
+export interface DeterministicR3fRenderDebug {
+    readonly frame: number;
+    readonly predictedFrame: number;
+    readonly verifiedFrame: number;
+    readonly correctionFrames: number;
+    readonly isPredicted: boolean;
+    readonly isVerified: boolean;
+    readonly checksum: string;
+}
+export interface DeterministicRenderPose {
+    readonly key: string;
+    readonly x: number;
+    readonly y?: number;
+    readonly z?: number;
+}
+export interface DeterministicR3fErrorCorrectionConfig<RenderState> {
+    readonly poses: (state: DeterministicRenderReadonly<RenderState>) => readonly DeterministicRenderPose[];
+    readonly errorCorrectionMs?: number;
+    readonly snapThreshold?: number;
+    readonly maxErrorSnapDistance?: number;
+}
+export interface DeterministicR3fRenderAdapter<State, Input, RenderState = State> {
+    getFrame(): DeterministicR3fRenderFrame<RenderState>;
+    setInput(slot: number, input: Input): void;
+    bindInput<RawInput>(slot: number, normalize: (rawInput: RawInput) => Input): (rawInput: RawInput) => Input;
+    update(deltaMs: number): number;
+    stepFrames(count: number): void;
+    subscribe(listener: (frame: DeterministicR3fRenderFrame<RenderState>) => void): () => void;
+    getSmoothedPose(key: string): DeterministicRenderPose | undefined;
+}
+export interface DeterministicR3fRenderAdapterConfig<State, Input, RenderState = State> {
+    readonly runtime: DeterministicOfflineRuntime<State, Input>;
+    readonly projectState?: (state: DeterministicRenderReadonly<State>) => RenderState;
+    readonly errorCorrection?: DeterministicR3fErrorCorrectionConfig<RenderState>;
+}
+export declare function createDeterministicR3fRenderAdapter<State, Input, RenderState = State>(config: DeterministicR3fRenderAdapterConfig<State, Input, RenderState>): DeterministicR3fRenderAdapter<State, Input, RenderState>;
+export declare function createDeterministicR3fDebugOverlay<RenderState>(frame: DeterministicR3fRenderFrame<RenderState>): DeterministicR3fRenderDebug;
+export declare function interpolateDeterministicRenderNumber(previous: number, next: number, alpha: number): number;
+export declare function interpolateDeterministicRenderVec2(previous: {
+    readonly x: number;
+    readonly y: number;
+}, next: {
+    readonly x: number;
+    readonly y: number;
+}, alpha: number): {
+    readonly x: number;
+    readonly y: number;
+};

package/dist/r3f-render-adapter.js

@@ -0,0 +1,203 @@
+import { cloneCanonical } from './canonical.js';
+export function createDeterministicR3fRenderAdapter(config) {
+    const smoother = config.errorCorrection === undefined ? undefined : createRenderErrorSmoother(config.errorCorrection);
+    if (smoother !== undefined && config.errorCorrection !== undefined) {
+        const extractPoses = config.errorCorrection.poses;
+        config.runtime.subscribe((frame) => {
+            smoother.observe(frame.frame, extractPoses(toRenderFrame(frame, config.projectState).state));
+        });
+    }
+    const adapter = {
+        getFrame() {
+            return toRenderFrame(config.runtime.getFrame(), config.projectState);
+        },
+        setInput(slot, input) {
+            config.runtime.setInput(slot, input);
+        },
+        bindInput(slot, normalize) {
+            return (rawInput) => {
+                const input = normalize(rawInput);
+                config.runtime.setInput(slot, input);
+                return input;
+            };
+        },
+        update(deltaMs) {
+            // Decay before stepping so a correction detected in this update renders
+            // at the full mispredicted pose first, then blends on subsequent updates.
+            smoother?.advance(deltaMs);
+            return config.runtime.update(deltaMs);
+        },
+        stepFrames(count) {
+            config.runtime.stepFrames(count);
+        },
+        subscribe(listener) {
+            return config.runtime.subscribe((frame) => {
+                listener(toRenderFrame(frame, config.projectState));
+            });
+        },
+        getSmoothedPose(key) {
+            if (smoother === undefined) {
+                throw new Error('getSmoothedPose requires errorCorrection to be configured on the render adapter');
+            }
+            return smoother.pose(key);
+        },
+    };
+    return adapter;
+}
+// Render-side only (plain floats, never fed back into sim state): when a
+// rollback re-emits an already-rendered frame with a different pose, the
+// rendered transform blends mispredicted -> corrected over errorCorrectionMs
+// instead of snapping (Quantum "Error Prediction" analog).
+function createRenderErrorSmoother(options) {
+    const windowMs = options.errorCorrectionMs ?? 120;
+    const snapThreshold = options.snapThreshold ?? 1e-6;
+    const maxErrorSnapDistance = options.maxErrorSnapDistance ?? Number.POSITIVE_INFINITY;
+    if (!Number.isFinite(windowMs) || windowMs < 0) {
+        throw new Error('errorCorrectionMs must be a finite number >= 0');
+    }
+    if (!Number.isFinite(snapThreshold) || snapThreshold < 0) {
+        throw new Error('snapThreshold must be a finite number >= 0');
+    }
+    if (Number.isNaN(maxErrorSnapDistance) || maxErrorSnapDistance < 0) {
+        throw new Error('maxErrorSnapDistance must be >= 0');
+    }
+    let lastFrame;
+    let tracked = new Map();
+    const errors = new Map();
+    function currentError(key) {
+        const entry = errors.get(key);
+        if (entry === undefined || windowMs <= 0) {
+            return { x: 0, y: 0, z: 0 };
+        }
+        const remaining = Math.min(1, Math.max(0, 1 - entry.elapsedMs / windowMs));
+        return { x: entry.x * remaining, y: entry.y * remaining, z: entry.z * remaining };
+    }
+    return {
+        observe(frame, poses) {
+            const isCorrection = lastFrame !== undefined && frame <= lastFrame;
+            const nextTracked = new Map();
+            for (const pose of poses) {
+                if (!Number.isFinite(pose.x) || (pose.y !== undefined && !Number.isFinite(pose.y)) || (pose.z !== undefined && !Number.isFinite(pose.z))) {
+                    throw new Error(`Render pose "${pose.key}" requires finite coordinates`);
+                }
+                if (nextTracked.has(pose.key)) {
+                    throw new Error(`Duplicate render pose key: ${pose.key}`);
+                }
+                const previous = tracked.get(pose.key);
+                if (isCorrection && previous !== undefined) {
+                    const carried = currentError(pose.key);
+                    const dx = previous.x + carried.x - pose.x;
+                    const dy = (previous.y ?? 0) + carried.y - (pose.y ?? 0);
+                    const dz = (previous.z ?? 0) + carried.z - (pose.z ?? 0);
+                    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+                    if (windowMs > 0 && distance > snapThreshold && distance <= maxErrorSnapDistance) {
+                        errors.set(pose.key, { x: dx, y: dy, z: dz, elapsedMs: 0 });
+                    }
+                    else {
+                        errors.delete(pose.key);
+                    }
+                }
+                nextTracked.set(pose.key, { x: pose.x, y: pose.y, z: pose.z });
+            }
+            tracked = nextTracked;
+            for (const key of [...errors.keys()]) {
+                if (!tracked.has(key)) {
+                    errors.delete(key);
+                }
+            }
+            lastFrame = frame;
+        },
+        advance(deltaMs) {
+            if (!Number.isFinite(deltaMs)) {
+                throw new Error('Render error-correction advance requires a finite deltaMs');
+            }
+            if (deltaMs <= 0) {
+                return;
+            }
+            for (const [key, entry] of errors) {
+                entry.elapsedMs += deltaMs;
+                if (entry.elapsedMs >= windowMs) {
+                    errors.delete(key);
+                }
+            }
+        },
+        pose(key) {
+            const base = tracked.get(key);
+            if (base === undefined) {
+                return undefined;
+            }
+            const error = currentError(key);
+            const result = { key, x: base.x + error.x };
+            if (base.y !== undefined) {
+                result.y = base.y + error.y;
+            }
+            if (base.z !== undefined) {
+                result.z = base.z + error.z;
+            }
+            return freezeRenderValue(result);
+        },
+    };
+}
+export function createDeterministicR3fDebugOverlay(frame) {
+    return freezeRenderValue({
+        frame: frame.frame,
+        predictedFrame: frame.predictedFrame,
+        verifiedFrame: frame.verifiedFrame,
+        correctionFrames: Math.max(0, frame.predictedFrame - frame.verifiedFrame),
+        isPredicted: frame.predictedFrame > frame.verifiedFrame,
+        isVerified: frame.predictedFrame === frame.verifiedFrame,
+        checksum: frame.checksum,
+    });
+}
+export function interpolateDeterministicRenderNumber(previous, next, alpha) {
+    if (!Number.isFinite(previous) || !Number.isFinite(next) || !Number.isFinite(alpha)) {
+        throw new Error('Render interpolation requires finite numbers');
+    }
+    const clampedAlpha = Math.min(1, Math.max(0, alpha));
+    return previous + (next - previous) * clampedAlpha;
+}
+export function interpolateDeterministicRenderVec2(previous, next, alpha) {
+    return freezeRenderValue({
+        x: interpolateDeterministicRenderNumber(previous.x, next.x, alpha),
+        y: interpolateDeterministicRenderNumber(previous.y, next.y, alpha),
+    });
+}
+function toRenderFrame(frame, projectState) {
+    const state = freezeRenderValue(cloneCanonical(frame.state));
+    const renderState = projectState === undefined ? state : projectState(state);
+    const frozenRenderState = freezeRenderValue(cloneCanonical(renderState));
+    const renderFrame = {
+        mode: frame.mode,
+        frame: frame.frame,
+        predictedFrame: frame.predictedFrame,
+        verifiedFrame: frame.verifiedFrame,
+        checksum: frame.checksum,
+        debug: freezeRenderValue({
+            frame: frame.frame,
+            predictedFrame: frame.predictedFrame,
+            verifiedFrame: frame.verifiedFrame,
+            correctionFrames: Math.max(0, frame.predictedFrame - frame.verifiedFrame),
+            isPredicted: frame.predictedFrame > frame.verifiedFrame,
+            isVerified: frame.predictedFrame === frame.verifiedFrame,
+            checksum: frame.checksum,
+        }),
+        state: frozenRenderState,
+    };
+    return freezeRenderValue(renderFrame);
+}
+function freezeRenderValue(value) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            freezeRenderValue(item);
+        }
+        return Object.freeze(value);
+    }
+    const record = value;
+    for (const key of Object.keys(record).sort()) {
+        freezeRenderValue(record[key]);
+    }
+    return Object.freeze(value);
+}

package/dist/random.d.ts

@@ -0,0 +1,13 @@
+export interface DeterministicRandomSnapshot {
+    readonly state: number;
+}
+export declare class DeterministicRandom {
+    private state;
+    constructor(seed: number);
+    nextUint32(): number;
+    nextInt(minInclusive: number, maxInclusive: number): number;
+    nextFixed(scale?: number): number;
+    fork(label: string | number): DeterministicRandom;
+    snapshot(): DeterministicRandomSnapshot;
+    restore(snapshot: DeterministicRandomSnapshot): void;
+}

package/dist/random.js

@@ -0,0 +1,55 @@
+export class DeterministicRandom {
+    state;
+    constructor(seed) {
+        this.state = seed >>> 0;
+        if (this.state === 0) {
+            this.state = 0x6d2b79f5;
+        }
+    }
+    nextUint32() {
+        let nextState = this.state;
+        nextState ^= nextState << 13;
+        nextState ^= nextState >>> 17;
+        nextState ^= nextState << 5;
+        this.state = nextState >>> 0;
+        return this.state;
+    }
+    nextInt(minInclusive, maxInclusive) {
+        if (!Number.isInteger(minInclusive) || !Number.isInteger(maxInclusive) || maxInclusive < minInclusive) {
+            throw new Error('nextInt requires integer bounds with max >= min');
+        }
+        const range = maxInclusive - minInclusive + 1;
+        return minInclusive + (this.nextUint32() % range);
+    }
+    nextFixed(scale = 1_000_000) {
+        if (!Number.isInteger(scale) || scale <= 0) {
+            throw new Error('nextFixed scale must be a positive integer');
+        }
+        return this.nextUint32() % scale;
+    }
+    fork(label) {
+        const labelHash = hashLabel(label);
+        const child = new DeterministicRandom(1);
+        child.restore({ state: (this.state ^ labelHash) >>> 0 });
+        return child;
+    }
+    snapshot() {
+        return { state: this.state };
+    }
+    restore(snapshot) {
+        // Mirror the constructor's zero-guard: xorshift32 is permanently dead at 0.
+        // Reachable via fork() when `state ^ labelHash` lands on 0 — a 1-in-2^32
+        // landmine per fork on a frozen deterministic RNG.
+        const state = snapshot.state >>> 0;
+        this.state = state === 0 ? 0x6d2b79f5 : state;
+    }
+}
+function hashLabel(label) {
+    const value = String(label);
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash;
+}

package/dist/replay-bundle.d.ts

@@ -0,0 +1,150 @@
+import { type CanonicalValue } from './canonical.js';
+import { type DeterministicFrameRuntime, type DeterministicFrameRuntimeDescriptor, type DeterministicSystem } from './engine-runtime.js';
+import type { RecordedChecksum, RecordedCommandFrame, RecordedDebugEvent, RecordedInputFrame } from './types.js';
+export interface DeterministicReplayBundle {
+    readonly schemaVersion: 1;
+    readonly runtimeVersion: string;
+    readonly engineHash: string;
+    readonly schemaHash: string;
+    readonly assetDbHash: string;
+    readonly configHash: string;
+    readonly sampleId: string;
+    readonly inputHistory: readonly RecordedInputFrame[];
+    readonly commandHistory: readonly RecordedCommandFrame[];
+    readonly checksums: readonly RecordedChecksum[];
+    readonly debugEvents: readonly RecordedDebugEvent[];
+    readonly snapshots: readonly DeterministicReplaySnapshot[];
+    readonly sliceOrigin?: DeterministicReplaySliceOrigin;
+    readonly runtimeReplay?: DeterministicReplayRuntimeManifest;
+    readonly semanticReplay?: DeterministicReplaySemanticModel;
+    readonly semanticReplayHash?: string;
+    readonly metadata: Readonly<Record<string, string | number | boolean>>;
+}
+export type DeterministicReplayRuntimeSystemId = 'score-accumulator-v1' | 'score-runtime-replay-v1' | 'project-game-state-runtime-replay-v1';
+export type DeterministicReplayRuntimeBeforeFrameId = 'score-input-command-delta-v1' | 'project-game-state-input-command-delta-v1';
+export interface DeterministicReplayRuntimeManifest {
+    readonly descriptor: DeterministicFrameRuntimeDescriptor;
+    readonly descriptorHash: string;
+    readonly systemId: DeterministicReplayRuntimeSystemId;
+    readonly beforeFrameId: DeterministicReplayRuntimeBeforeFrameId;
+    readonly systemsSourceHash: string;
+    readonly acceptedSystemsSourceHashes?: readonly string[];
+    readonly seed: number;
+    readonly sparse?: boolean;
+    readonly manifestHash: string;
+}
+export interface DeterministicReplaySliceOrigin {
+    readonly sourceBundleHash: string;
+    readonly sourceStartFrame: number;
+    readonly sourceEndFrame: number;
+    readonly sliceStartFrame: number;
+    readonly sliceEndFrame: number;
+    readonly baselineSnapshot: DeterministicReplaySnapshot;
+}
+export interface DeterministicReplaySnapshot {
+    readonly frame: number;
+    readonly checksum: string;
+    readonly bytes: string;
+}
+export interface DeterministicReplaySemanticModel {
+    readonly kind: 'operation-model-v1';
+    readonly initialState: CanonicalValue;
+    readonly operations: readonly DeterministicReplaySemanticOperation[];
+}
+export interface DeterministicReplaySemanticOperation {
+    readonly source: 'input' | 'command' | 'command.payload';
+    readonly sourcePath: string;
+    readonly targetPath: string;
+    readonly op: 'add' | 'set';
+    readonly slotField?: string;
+}
+export interface DeterministicReplayBundleVerification {
+    readonly result: 'pass' | 'fail';
+    readonly bundleHash: string;
+    readonly replayBytes: number;
+    readonly snapshotBytes: number;
+    readonly inputCount: number;
+    readonly checksumCount: number;
+    readonly commandCount: number;
+    readonly debugEventCount: number;
+    readonly semanticReplayExecuted: boolean;
+    readonly semanticReplayFrames: number;
+    readonly firstMismatch?: DeterministicReplayBundleMismatch;
+}
+export interface DeterministicReplayBundleMismatch {
+    readonly frame: number;
+    readonly subsystem: string;
+    readonly path: string;
+    readonly expectedChecksum: string;
+    readonly actualChecksum: string;
+    readonly minimalReproPath: string;
+}
+export interface DeterministicReplayDesyncMinimization {
+    readonly mismatch: DeterministicReplayBundleMismatch;
+    readonly bundle: DeterministicReplayBundle;
+    readonly verifier: DeterministicReplayBundleVerification;
+    readonly searchSteps: number;
+    readonly originalReplayBytes: number;
+    readonly minimizedReplayBytes: number;
+    readonly removedInputFrames: number;
+    readonly removedInputs: number;
+    readonly removedCommandFrames: number;
+    readonly removedCommands: number;
+    readonly removedDebugEvents: number;
+    readonly removedSnapshots: number;
+    readonly removedChecksumFrames: number;
+}
+export interface DeterministicFrameRuntimeReplayBundleOptions {
+    readonly descriptor: DeterministicFrameRuntimeDescriptor;
+    readonly systems: Readonly<Record<string, DeterministicSystem>>;
+    readonly descriptorHash?: string;
+    readonly systemsSourceHash?: string;
+    readonly requireRuntimeIdentity?: boolean;
+    readonly seed?: number;
+    readonly sparse?: boolean;
+    beforeFrame?(runtime: DeterministicFrameRuntime, frame: number, inputs: RecordedInputFrame['inputs'], commands: RecordedCommandFrame['commands']): void;
+}
+export interface DeterministicFrameRuntimeReplayBundleVerification {
+    readonly result: 'pass' | 'fail';
+    readonly bundleHash: string;
+    readonly frames: number;
+    readonly baselineFrame: number;
+    readonly finalFrame: number;
+    readonly finalChecksum: string;
+    readonly firstMismatch?: DeterministicReplayBundleMismatch;
+}
+export interface DeterministicReplayRuntimeManifestSource {
+    readonly descriptor: DeterministicFrameRuntimeDescriptor;
+    readonly descriptorHash?: string;
+    readonly systemId: DeterministicReplayRuntimeSystemId;
+    readonly beforeFrameId: DeterministicReplayRuntimeBeforeFrameId;
+    readonly systemsSourceHash?: string;
+    readonly acceptedSystemsSourceHashes?: readonly string[];
+    readonly seed?: number;
+    readonly sparse?: boolean;
+}
+export interface DeterministicReplayDebugTables {
+    readonly ecs: readonly CanonicalValue[];
+    readonly physics: readonly CanonicalValue[];
+    readonly navigation: readonly CanonicalValue[];
+    readonly commands: readonly CanonicalValue[];
+    readonly events: readonly CanonicalValue[];
+    readonly rng: readonly CanonicalValue[];
+    readonly assets: readonly CanonicalValue[];
+    readonly timings: readonly CanonicalValue[];
+    readonly checksum: string;
+}
+export declare function createDeterministicReplayBundle(bundle: Omit<DeterministicReplayBundle, 'schemaVersion'>): DeterministicReplayBundle;
+export declare function createDeterministicReplayRuntimeManifest(source: DeterministicReplayRuntimeManifestSource): DeterministicReplayRuntimeManifest;
+export declare function verifyDeterministicReplayBundle(bundle: DeterministicReplayBundle, expected?: Partial<Pick<DeterministicReplayBundle, 'engineHash' | 'schemaHash' | 'assetDbHash' | 'configHash' | 'runtimeVersion' | 'semanticReplayHash'>>): DeterministicReplayBundleVerification;
+export declare function verifyDeterministicFrameRuntimeReplayBundle(bundle: DeterministicReplayBundle, options: DeterministicFrameRuntimeReplayBundleOptions): DeterministicFrameRuntimeReplayBundleVerification;
+export declare function verifyDeterministicSelfContainedFrameRuntimeReplayBundle(bundle: DeterministicReplayBundle, options?: {
+    readonly sparse?: boolean;
+}): DeterministicFrameRuntimeReplayBundleVerification;
+export declare function minimizeDeterministicReplayDesync(expected: DeterministicReplayBundle, actual: DeterministicReplayBundle): DeterministicReplayBundleMismatch | undefined;
+export declare function minimizeDeterministicReplayDesyncBundle(expected: DeterministicReplayBundle, actual: DeterministicReplayBundle): DeterministicReplayDesyncMinimization | undefined;
+export declare function createDeterministicReplayDebugTables(events: readonly RecordedDebugEvent[]): DeterministicReplayDebugTables;
+export declare function sliceDeterministicReplayBundle(bundle: DeterministicReplayBundle, startFrame: number, endFrame: number): DeterministicReplayBundle;
+export declare const __replayBundleCoverageProof: {
+    readonly exercisePrivateFallbacks: () => Readonly<Record<string, CanonicalValue>>;
+};