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

package/dist/signals.js

@@ -0,0 +1,99 @@
+import { cloneCanonical, defaultChecksum } from './canonical.js';
+export function createDeterministicSignalBus(subscriptions) {
+    const orderedSubscriptions = [...subscriptions].sort(compareSubscriptions);
+    const emitted = [];
+    const dispatched = [];
+    let sequence = 0;
+    return {
+        emit(signal) {
+            emitted.push({ sequence, signal: cloneCanonical(signal) });
+            sequence += 1;
+        },
+        dispatch(state, frame) {
+            let nextState = cloneCanonical(state);
+            const due = emitted
+                .filter((entry) => entry.signal.frame <= frame)
+                .sort(compareQueuedSignals);
+            for (const entry of due) {
+                for (const subscription of orderedSubscriptions) {
+                    if (subscription.type === entry.signal.type) {
+                        nextState = subscription.handle(nextState, entry.signal);
+                    }
+                }
+                dispatched.push(cloneCanonical(entry.signal));
+            }
+            const dueSequences = new Set(due.map((entry) => entry.sequence));
+            for (let index = emitted.length - 1; index >= 0; index -= 1) {
+                if (dueSequences.has(emitted[index].sequence)) {
+                    emitted.splice(index, 1);
+                }
+            }
+            return nextState;
+        },
+        snapshot() {
+            const snapshot = {
+                emitted: emitted.sort(compareQueuedSignals).map((entry) => entry.signal),
+                dispatched,
+                sequence,
+            };
+            return cloneCanonical(snapshot);
+        },
+        restore(snapshot) {
+            emitted.length = 0;
+            snapshot.emitted.forEach((signal, index) => emitted.push({ sequence: index, signal: cloneCanonical(signal) }));
+            dispatched.length = 0;
+            snapshot.dispatched.forEach((signal) => dispatched.push(cloneCanonical(signal)));
+            sequence = snapshot.sequence;
+        },
+    };
+}
+export function runDeterministicSignalFixture() {
+    const subscriptions = [
+        {
+            id: 'score',
+            type: 'hit',
+            order: 20,
+            handle: (state, signal) => ({
+                ...state,
+                score: state.score + Number(signal.payload.points),
+                trace: [...state.trace, `score:${signal.payload.points}`],
+            }),
+        },
+        {
+            id: 'damage',
+            type: 'hit',
+            order: 10,
+            handle: (state, signal) => ({
+                ...state,
+                damage: state.damage + Number(signal.payload.damage),
+                trace: [...state.trace, `damage:${signal.payload.damage}`],
+            }),
+        },
+    ];
+    const bus = createDeterministicSignalBus(subscriptions);
+    const initial = { score: 0, damage: 0, trace: [] };
+    bus.emit({ frame: 2, type: 'hit', payload: { points: 3, damage: 1 } });
+    bus.emit({ frame: 1, type: 'hit', payload: { points: 5, damage: 2 } });
+    const snapshot = bus.snapshot();
+    const after = bus.dispatch(bus.dispatch(initial, 1), 2);
+    const checksum = defaultChecksum(after);
+    const restoredBus = createDeterministicSignalBus(subscriptions);
+    restoredBus.restore(snapshot);
+    const restored = restoredBus.dispatch(restoredBus.dispatch(initial, 1), 2);
+    return {
+        checksum,
+        restoredChecksum: defaultChecksum(restored),
+        dispatchedSignals: bus.snapshot().dispatched.length,
+        subscriptionOrderStable: after.trace.join('|') === 'damage:2|score:5|damage:1|score:3',
+        rollbackEquivalent: checksum === defaultChecksum(restored),
+    };
+}
+function compareSubscriptions(left, right) {
+    return left.order - right.order || compareStrings(left.id, right.id);
+}
+function compareQueuedSignals(left, right) {
+    return left.signal.frame - right.signal.frame || left.sequence - right.sequence;
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/sparse-set.d.ts

@@ -0,0 +1,34 @@
+export interface DeterministicSparseSetSnapshot<T> {
+    readonly capacity: number;
+    readonly dense: readonly number[];
+    readonly values: readonly T[];
+    readonly sparseEntries: readonly {
+        readonly id: number;
+        readonly denseIndex: number;
+    }[];
+}
+export interface DeterministicSparseSet<T> {
+    add(id: number, value: T): void;
+    remove(id: number): boolean;
+    has(id: number): boolean;
+    get(id: number): T | undefined;
+    set(id: number, value: T): void;
+    query(): readonly {
+        readonly id: number;
+        readonly value: T;
+    }[];
+    snapshot(): DeterministicSparseSetSnapshot<T>;
+    restore(snapshot: DeterministicSparseSetSnapshot<T>): void;
+    checksum(): string;
+}
+export interface DeterministicSparseSetFixtureResult {
+    readonly checksum: string;
+    readonly restoredChecksum: string;
+    readonly queryOrderStable: boolean;
+    readonly denseCount: number;
+    readonly rejectedDuplicate: boolean;
+    readonly rejectedMalformedSnapshot: boolean;
+    readonly removed: number;
+}
+export declare function createDeterministicSparseSet<T>(capacity?: number): DeterministicSparseSet<T>;
+export declare function runDeterministicSparseSetFixture(): DeterministicSparseSetFixtureResult;

package/dist/sparse-set.js

@@ -0,0 +1,165 @@
+import { cloneCanonical, defaultChecksum } from './canonical.js';
+export function createDeterministicSparseSet(capacity = 1024) {
+    const dense = [];
+    const values = [];
+    const sparse = new Map();
+    function assertId(id) {
+        if (!Number.isInteger(id) || id < 0 || id >= capacity) {
+            throw new Error(`Sparse-set id ${id} outside capacity ${capacity}`);
+        }
+    }
+    return {
+        add(id, value) {
+            assertId(id);
+            if (sparse.has(id)) {
+                throw new Error(`Sparse-set duplicate id ${id}`);
+            }
+            sparse.set(id, dense.length);
+            dense.push(id);
+            values.push(cloneCanonical(value));
+        },
+        remove(id) {
+            assertId(id);
+            const index = sparse.get(id);
+            if (index === undefined) {
+                return false;
+            }
+            const lastIndex = dense.length - 1;
+            const lastId = dense[lastIndex];
+            dense[index] = lastId;
+            values[index] = values[lastIndex];
+            sparse.set(lastId, index);
+            dense.pop();
+            values.pop();
+            sparse.delete(id);
+            return true;
+        },
+        has(id) {
+            assertId(id);
+            return sparse.has(id);
+        },
+        get(id) {
+            assertId(id);
+            const index = sparse.get(id);
+            return index === undefined ? undefined : cloneCanonical(values[index]);
+        },
+        set(id, value) {
+            assertId(id);
+            const index = sparse.get(id);
+            if (index === undefined) {
+                throw new Error(`Sparse-set missing id ${id}`);
+            }
+            values[index] = cloneCanonical(value);
+        },
+        query() {
+            return dense.map((id, index) => ({ id, value: cloneCanonical(values[index]) }))
+                .sort((left, right) => left.id - right.id);
+        },
+        snapshot() {
+            return cloneCanonical({
+                capacity,
+                dense,
+                values,
+                sparseEntries: [...sparse.entries()]
+                    .map(([id, denseIndex]) => ({ id, denseIndex }))
+                    .sort((left, right) => left.id - right.id),
+            });
+        },
+        restore(snapshot) {
+            if (snapshot.capacity !== capacity) {
+                throw new Error(`Sparse-set capacity mismatch ${snapshot.capacity} !== ${capacity}`);
+            }
+            validateSparseSetSnapshot(snapshot, capacity);
+            dense.length = 0;
+            values.length = 0;
+            sparse.clear();
+            snapshot.dense.forEach((id, index) => {
+                dense.push(id);
+                values.push(cloneCanonical(snapshot.values[index]));
+                sparse.set(id, index);
+            });
+        },
+        checksum() {
+            return defaultChecksum(this.snapshot());
+        },
+    };
+}
+export function runDeterministicSparseSetFixture() {
+    const set = createDeterministicSparseSet(512);
+    let rejectedDuplicate = false;
+    let removed = 0;
+    for (let index = 0; index < 256; index += 1) {
+        set.add((index * 37) % 512, { hp: 100 - (index % 17), team: index % 4 });
+    }
+    try {
+        set.add(0, { hp: 1, team: 1 });
+    }
+    catch {
+        rejectedDuplicate = true;
+    }
+    for (let id = 0; id < 512; id += 5) {
+        removed += set.remove(id) ? 1 : 0;
+    }
+    for (const entry of set.query()) {
+        set.set(entry.id, { hp: entry.value.hp + 1, team: entry.value.team });
+    }
+    const checksum = set.checksum();
+    const firstQuery = set.query().map((entry) => entry.id);
+    const snapshot = set.snapshot();
+    const restored = createDeterministicSparseSet(512);
+    restored.restore(snapshot);
+    let rejectedMalformedSnapshot = false;
+    try {
+        restored.restore({ ...snapshot, sparseEntries: snapshot.sparseEntries.slice(1) });
+    }
+    catch {
+        rejectedMalformedSnapshot = true;
+    }
+    return {
+        checksum,
+        restoredChecksum: restored.checksum(),
+        queryOrderStable: defaultChecksum(firstQuery) === defaultChecksum(restored.query().map((entry) => entry.id)),
+        denseCount: snapshot.dense.length,
+        rejectedDuplicate,
+        rejectedMalformedSnapshot,
+        removed,
+    };
+}
+function validateSparseSetSnapshot(snapshot, capacity) {
+    if (snapshot.dense.length !== snapshot.values.length) {
+        throw new Error(`Sparse-set snapshot dense/value length mismatch ${snapshot.dense.length} !== ${snapshot.values.length}`);
+    }
+    if (snapshot.sparseEntries.length !== snapshot.dense.length) {
+        throw new Error(`Sparse-set snapshot sparse/dense length mismatch ${snapshot.sparseEntries.length} !== ${snapshot.dense.length}`);
+    }
+    const denseIds = new Set();
+    for (const id of snapshot.dense) {
+        if (!Number.isInteger(id) || id < 0 || id >= capacity) {
+            throw new Error(`Sparse-set snapshot id ${id} outside capacity ${capacity}`);
+        }
+        if (denseIds.has(id)) {
+            throw new Error(`Sparse-set snapshot duplicate dense id ${id}`);
+        }
+        denseIds.add(id);
+    }
+    const sparseIds = new Set();
+    const sparseById = new Map();
+    for (const entry of snapshot.sparseEntries) {
+        if (!Number.isInteger(entry.id) || entry.id < 0 || entry.id >= capacity) {
+            throw new Error(`Sparse-set snapshot sparse id ${entry.id} outside capacity ${capacity}`);
+        }
+        if (!Number.isInteger(entry.denseIndex) || entry.denseIndex < 0 || entry.denseIndex >= snapshot.dense.length) {
+            throw new Error(`Sparse-set snapshot dense index ${entry.denseIndex} outside dense length ${snapshot.dense.length}`);
+        }
+        if (sparseIds.has(entry.id)) {
+            throw new Error(`Sparse-set snapshot duplicate sparse id ${entry.id}`);
+        }
+        sparseIds.add(entry.id);
+        sparseById.set(entry.id, entry.denseIndex);
+    }
+    for (const [index, id] of snapshot.dense.entries()) {
+        if (sparseById.get(id) !== index) {
+            throw new Error(`Sparse-set snapshot sparse entry mismatch for id ${id}`);
+        }
+    }
+}

package/dist/synctest.d.ts

@@ -0,0 +1,31 @@
+import { DeterministicRandom } from './random.js';
+import type { DeterministicSessionConfig } from './types.js';
+export type SyncplaySynctestPhase = 'straight' | 'rollback' | 'replay';
+export type SyncplaySynctestInputFuzz<Input> = (random: DeterministicRandom, slot: number, frame: number) => Input;
+export interface SyncplaySynctestConfig<State, Input> extends DeterministicSessionConfig<State, Input> {
+    readonly frames?: number;
+    readonly seeds?: readonly number[];
+    readonly inputFuzz?: SyncplaySynctestInputFuzz<Input>;
+}
+export interface SyncplaySynctestDivergence {
+    readonly seed: number;
+    readonly frame: number;
+    readonly phase: SyncplaySynctestPhase;
+    readonly straightChecksum: string;
+    readonly rollbackChecksum: string;
+}
+export interface SyncplaySynctestResult {
+    readonly ok: boolean;
+    readonly seedsRun: number;
+    readonly framesChecked: number;
+    readonly firstDivergence?: SyncplaySynctestDivergence;
+}
+/**
+ * GGPO-style offline synctest: for every seed, runs the game straight through
+ * and again with a rollback (snapshot → step → restore → re-step) on EVERY
+ * frame, comparing per-frame checksums, then re-verifies the exported replay
+ * from scratch. Catches logic nondeterminism (stray Math.random, iteration
+ * order dependence, restore-sensitive state) with no networking involved.
+ * Divergence is reported in the result, never thrown; config errors throw.
+ */
+export declare function runSyncplaySynctest<State, Input>(config: SyncplaySynctestConfig<State, Input>): SyncplaySynctestResult;

package/dist/synctest.js

@@ -0,0 +1,133 @@
+import { stableSortedKeys } from './collections.js';
+import { SyncplayError, invariant } from './errors.js';
+import { createOfflineSession } from './offline-session.js';
+import { DeterministicRandom } from './random.js';
+import { verifyReplay } from './replay.js';
+/**
+ * GGPO-style offline synctest: for every seed, runs the game straight through
+ * and again with a rollback (snapshot → step → restore → re-step) on EVERY
+ * frame, comparing per-frame checksums, then re-verifies the exported replay
+ * from scratch. Catches logic nondeterminism (stray Math.random, iteration
+ * order dependence, restore-sensitive state) with no networking involved.
+ * Divergence is reported in the result, never thrown; config errors throw.
+ */
+export function runSyncplaySynctest(config) {
+    const { frames: framesOption, seeds: seedsOption, inputFuzz: inputFuzzOption, ...sessionBase } = config;
+    const frames = framesOption ?? 300;
+    const seeds = seedsOption ?? [1, 2, 3];
+    invariant(Number.isInteger(frames) && frames >= 1, 'synctest frames must be a positive integer', 'synctest.frames');
+    invariant(seeds.length > 0 && seeds.every((seed) => Number.isInteger(seed)), 'synctest seeds must be a non-empty list of integers', 'synctest.seeds');
+    const inputFuzz = inputFuzzOption ?? createDefaultInputFuzz(config.defaultInput);
+    let seedsRun = 0;
+    let framesChecked = 0;
+    for (const seed of seeds) {
+        seedsRun += 1;
+        let lastChecksum;
+        const sessionConfig = {
+            ...sessionBase,
+            randomSeed: seed,
+            checksumIntervalFrames: 1,
+            replayRecordingMode: 'memory',
+            onChecksumRecorded(checksum) {
+                lastChecksum = checksum;
+                sessionBase.onChecksumRecorded?.(checksum);
+            },
+        };
+        const straight = createOfflineSession(sessionConfig);
+        const schedule = buildInputSchedule(config.playerCount, frames, seed, inputFuzz);
+        const straightChecksums = [];
+        for (let frame = 0; frame < frames; frame += 1) {
+            applyScheduledInputs(straight, schedule[frame]);
+            straight.stepFrames(1);
+            straightChecksums.push(takeChecksum(lastChecksum, straight.currentFrame));
+        }
+        const replay = straight.exportReplay();
+        const rollback = createOfflineSession(sessionConfig);
+        for (let frame = 0; frame < frames; frame += 1) {
+            applyScheduledInputs(rollback, schedule[frame]);
+            rollback.stepFrames(1);
+            const firstPass = takeChecksum(lastChecksum, rollback.currentFrame);
+            rollback.restoreToFrame(frame);
+            applyScheduledInputs(rollback, schedule[frame]);
+            rollback.stepFrames(1);
+            const secondPass = takeChecksum(lastChecksum, rollback.currentFrame);
+            framesChecked += 1;
+            const straightChecksum = straightChecksums[frame];
+            if (firstPass !== straightChecksum) {
+                return diverged(seedsRun, framesChecked, {
+                    seed,
+                    frame: frame + 1,
+                    phase: 'straight',
+                    straightChecksum,
+                    rollbackChecksum: firstPass,
+                });
+            }
+            if (secondPass !== straightChecksum) {
+                return diverged(seedsRun, framesChecked, {
+                    seed,
+                    frame: frame + 1,
+                    phase: 'rollback',
+                    straightChecksum,
+                    rollbackChecksum: secondPass,
+                });
+            }
+        }
+        const replayResult = verifyReplay({ ...sessionBase, replay, throwOnMismatch: false });
+        if (replayResult.firstMismatch !== undefined) {
+            return diverged(seedsRun, framesChecked, {
+                seed,
+                frame: replayResult.firstMismatch.frame,
+                phase: 'replay',
+                straightChecksum: replayResult.firstMismatch.expectedChecksum,
+                rollbackChecksum: replayResult.firstMismatch.actualChecksum,
+            });
+        }
+    }
+    return { ok: true, seedsRun, framesChecked };
+}
+function diverged(seedsRun, framesChecked, firstDivergence) {
+    return { ok: false, seedsRun, framesChecked, firstDivergence };
+}
+function takeChecksum(lastChecksum, frame) {
+    if (lastChecksum === undefined || lastChecksum.frame !== frame) {
+        throw new SyncplayError(`Synctest expected a checksum record for frame ${frame}`, {
+            code: 'synctest.missing-checksum',
+            frame,
+        });
+    }
+    return lastChecksum.checksum;
+}
+function buildInputSchedule(playerCount, frames, seed, inputFuzz) {
+    const random = new DeterministicRandom(seed >>> 0).fork('synctest.input-fuzz');
+    const schedule = [];
+    for (let frame = 0; frame < frames; frame += 1) {
+        schedule.push(Array.from({ length: playerCount }, (_, slot) => inputFuzz(random, slot, frame)));
+    }
+    return schedule;
+}
+function applyScheduledInputs(session, inputs) {
+    inputs.forEach((input, slot) => session.setInput(slot, input));
+}
+function createDefaultInputFuzz(defaultInput) {
+    return (random) => fuzzFromTemplate(defaultInput, random);
+}
+function fuzzFromTemplate(template, random) {
+    if (typeof template === 'boolean') {
+        return random.nextInt(0, 1) === 1;
+    }
+    if (typeof template === 'number') {
+        return random.nextInt(-1, 1);
+    }
+    if (Array.isArray(template)) {
+        return template.map((item) => fuzzFromTemplate(item, random));
+    }
+    if (template !== null && typeof template === 'object' && Object.getPrototypeOf(template) === Object.prototype) {
+        const record = template;
+        const fuzzed = {};
+        for (const key of stableSortedKeys(record)) {
+            fuzzed[key] = fuzzFromTemplate(record[key], random);
+        }
+        return fuzzed;
+    }
+    return template;
+}

package/dist/system-lifecycle.d.ts

@@ -0,0 +1,72 @@
+import { type CanonicalValue } from './canonical.js';
+export interface DeterministicLifecycleSystemDescriptor {
+    readonly id: string;
+    readonly order: number;
+    readonly startEnabled?: boolean;
+    readonly parentId?: string;
+    readonly signalsOnly?: boolean;
+}
+export interface DeterministicLifecycleSystemHooks {
+    readonly onInit?: (ctx: DeterministicLifecycleSystemContext) => void;
+    readonly onEnabled?: (ctx: DeterministicLifecycleSystemContext) => void;
+    readonly onDisabled?: (ctx: DeterministicLifecycleSystemContext) => void;
+    readonly update?: (ctx: DeterministicLifecycleSystemContext) => void;
+    readonly signal?: (ctx: DeterministicLifecycleSystemContext, signal: DeterministicLifecycleSignal) => void;
+}
+export interface DeterministicLifecycleSignal {
+    readonly id: string;
+    readonly payload: CanonicalValue;
+}
+export interface DeterministicLifecycleSystemContext {
+    readonly frame: number;
+    readonly systemId: string;
+    emit(event: string): void;
+    increment(key: string, amount?: number): void;
+    signal(signal: DeterministicLifecycleSignal): void;
+}
+export interface DeterministicLifecycleSnapshot {
+    readonly frame: number;
+    readonly initialized: readonly string[];
+    readonly enabled: readonly string[];
+    readonly counters: Readonly<Record<string, number>>;
+    readonly pendingSignals: readonly DeterministicLifecycleSignal[];
+    readonly log: readonly string[];
+    readonly checksum: string;
+}
+export interface DeterministicLifecycleRunner {
+    readonly frame: number;
+    enable(systemId: string): void;
+    disable(systemId: string): void;
+    signal(signal: DeterministicLifecycleSignal): void;
+    step(): void;
+    snapshot(): DeterministicLifecycleSnapshot;
+    restore(snapshot: DeterministicLifecycleSnapshot): void;
+}
+export interface DeterministicLifecycleFixtureResult {
+    readonly checksum: string;
+    readonly restoredChecksum: string;
+    readonly rollbackEquivalent: boolean;
+    readonly initCalls: number;
+    readonly updateCalls: number;
+    readonly enabledCalls: number;
+    readonly disabledCalls: number;
+    readonly signalCalls: number;
+    readonly hierarchySkippedUpdates: number;
+    readonly startDisabledCovered: boolean;
+    readonly signalOnlySkippedUpdate: boolean;
+    readonly orderStable: boolean;
+}
+export interface DeterministicLifecycleCounterSummary {
+    readonly initCalls: number;
+    readonly updateCalls: number;
+    readonly enabledCalls: number;
+    readonly disabledCalls: number;
+    readonly signalCalls: number;
+    readonly hierarchySkippedUpdates: number;
+    readonly startDisabledCovered: boolean;
+    readonly signalOnlySkippedUpdate: boolean;
+    readonly orderStable: boolean;
+}
+export declare function createDeterministicLifecycleRunner(descriptors: readonly DeterministicLifecycleSystemDescriptor[], hooks: Readonly<Record<string, DeterministicLifecycleSystemHooks>>): DeterministicLifecycleRunner;
+export declare function runDeterministicLifecycleFixture(frames?: number): DeterministicLifecycleFixtureResult;
+export declare function summarizeDeterministicLifecycleCounters(counters: Readonly<Record<string, number>>, log: readonly string[]): DeterministicLifecycleCounterSummary;