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

package/dist/input-authority.js

@@ -0,0 +1,147 @@
+import { defaultChecksum } from './canonical.js';
+import { invariant } from './errors.js';
+export function createInputAuthority(config) {
+    invariant(Number.isInteger(config.playerCount) && config.playerCount >= 1, 'playerCount must be a positive integer', 'input-authority.player-count');
+    invariant(Number.isInteger(config.hardToleranceTicks) && config.hardToleranceTicks >= 0, 'hardToleranceTicks must be a non-negative integer', 'input-authority.hard-tolerance');
+    const playerCount = config.playerCount;
+    const maxFutureTicks = config.maxFutureTicks ?? Number.POSITIVE_INFINITY;
+    const retainedConfirmedFrames = config.retainedConfirmedFrames ?? 512;
+    const pending = new Map();
+    const lastConfirmedInput = Array.from({ length: playerCount }, () => config.neutralInput);
+    const retained = new Map();
+    let confirmedThrough = -1;
+    let earliestRetained = -1;
+    let confirmedTicks = 0;
+    if (config.restoreFrom !== undefined) {
+        const { confirmedThrough: restoredThrough, frames } = config.restoreFrom;
+        invariant(frames.length > 0, 'restoreFrom requires at least one frame', 'input-authority.restore-empty');
+        for (let index = 0; index < frames.length; index += 1) {
+            const frame = frames[index];
+            invariant(Number.isInteger(frame.tick) && (index === 0 || frame.tick === frames[index - 1].tick + 1), 'restoreFrom frames must be tick-contiguous', 'input-authority.restore-gap');
+            invariant(frame.inputs.length === playerCount, 'restoreFrom frame inputs must cover every player slot', 'input-authority.restore-inputs');
+            retained.set(frame.tick, frame);
+        }
+        invariant(frames[frames.length - 1].tick === restoredThrough, 'restoreFrom frames must end at the restored frontier', 'input-authority.restore-frontier');
+        earliestRetained = frames[0].tick;
+        confirmedThrough = restoredThrough;
+        const lastFrame = frames[frames.length - 1];
+        for (let slot = 0; slot < playerCount; slot += 1) {
+            lastConfirmedInput[slot] = lastFrame.inputs[slot];
+        }
+    }
+    let substitutedInputs = 0;
+    let droppedLateInputs = 0;
+    let rejectedFutureInputs = 0;
+    function receiveInput(slot, tick, input) {
+        if (!Number.isInteger(slot) || slot < 0 || slot >= playerCount) {
+            return { accepted: false, reason: 'slot-out-of-range' };
+        }
+        if (!Number.isInteger(tick) || tick < 0) {
+            return { accepted: false, reason: 'invalid-tick' };
+        }
+        if (tick <= confirmedThrough) {
+            droppedLateInputs += 1;
+            return { accepted: false, reason: 'tick-already-confirmed' };
+        }
+        if (tick > confirmedThrough + maxFutureTicks) {
+            rejectedFutureInputs += 1;
+            return { accepted: false, reason: 'tick-too-far-ahead' };
+        }
+        let slots = pending.get(tick);
+        if (slots === undefined) {
+            slots = Array.from({ length: playerCount }, () => undefined);
+            pending.set(tick, slots);
+        }
+        slots[slot] = input;
+        return { accepted: true };
+    }
+    function confirmTick(tick) {
+        const slots = pending.get(tick);
+        const inputs = [];
+        const substitutedSlots = [];
+        for (let slot = 0; slot < playerCount; slot += 1) {
+            const submitted = slots?.[slot];
+            if (submitted === undefined) {
+                inputs.push(lastConfirmedInput[slot]);
+                substitutedSlots.push(slot);
+                substitutedInputs += 1;
+            }
+            else {
+                inputs.push(submitted);
+                lastConfirmedInput[slot] = submitted;
+            }
+        }
+        pending.delete(tick);
+        const frame = {
+            tick,
+            inputs,
+            substitutedSlots,
+            checksum: String(defaultChecksum({ tick, inputs })),
+        };
+        retained.set(tick, frame);
+        if (earliestRetained === -1) {
+            earliestRetained = tick;
+        }
+        if (retained.size > retainedConfirmedFrames) {
+            const oldest = tick - retainedConfirmedFrames;
+            if (retained.delete(oldest)) {
+                earliestRetained = oldest + 1;
+            }
+        }
+        confirmedThrough = tick;
+        confirmedTicks += 1;
+        return frame;
+    }
+    function advance(now) {
+        const frames = [];
+        let next = confirmedThrough + 1;
+        while (next <= now) {
+            const slots = pending.get(next);
+            const allPresent = slots !== undefined && slots.every((value) => value !== undefined);
+            const deadlinePassed = now - next >= config.hardToleranceTicks;
+            if (!allPresent && !deadlinePassed) {
+                break;
+            }
+            frames.push(confirmTick(next));
+            next += 1;
+        }
+        return frames;
+    }
+    return {
+        playerCount,
+        get confirmedThrough() {
+            return confirmedThrough;
+        },
+        receiveInput,
+        advance,
+        get earliestRetainedTick() {
+            return earliestRetained;
+        },
+        confirmedFrame(tick) {
+            return retained.get(tick);
+        },
+        confirmedFrameRange(from, to) {
+            invariant(Number.isInteger(from) && Number.isInteger(to) && from <= to, 'confirmedFrameRange requires an ordered integer range', 'input-authority.range-invalid');
+            const frames = [];
+            for (let tick = from; tick <= to; tick += 1) {
+                const frame = retained.get(tick);
+                invariant(frame !== undefined, `confirmed frame ${tick} is no longer retained`, 'input-authority.range-unavailable');
+                frames.push(frame);
+            }
+            return frames;
+        },
+        pruneConfirmedBefore(tick) {
+            invariant(Number.isInteger(tick) && tick <= confirmedThrough + 1, 'pruneConfirmedBefore tick must be an integer at or below the confirmed frontier + 1', 'input-authority.prune-tick');
+            if (earliestRetained === -1 || tick <= earliestRetained) {
+                return;
+            }
+            for (let t = earliestRetained; t < tick; t += 1) {
+                retained.delete(t);
+            }
+            earliestRetained = tick;
+        },
+        stats() {
+            return { confirmedTicks, substitutedInputs, droppedLateInputs, rejectedFutureInputs };
+        },
+    };
+}

package/dist/input-button.d.ts

@@ -0,0 +1,36 @@
+import type { CanonicalValue } from './canonical.js';
+export interface DeterministicButtonState {
+    readonly down: boolean;
+    readonly previousDown: boolean;
+    readonly pressedFrame: number;
+    readonly releasedFrame: number;
+}
+export interface DeterministicButtonStep {
+    readonly state: DeterministicButtonState;
+    readonly isDown: boolean;
+    readonly wasPressed: boolean;
+    readonly wasReleased: boolean;
+    readonly checksum: string;
+}
+export interface DeterministicButtonFixtureResult {
+    readonly checksum: string;
+    readonly restoredChecksum: string;
+    readonly rollbackEquivalent: boolean;
+    readonly pressedCount: number;
+    readonly releasedCount: number;
+    readonly heldFrames: number;
+    readonly repeatedFrames: number;
+    readonly transitionsStable: boolean;
+}
+export interface DeterministicDescriptorButtonFixtureResult extends DeterministicButtonFixtureResult {
+    readonly descriptorArtifactId: string;
+    readonly descriptorButtonFields: number;
+    readonly serializedBytes: number;
+    readonly defaultApplied: boolean;
+    readonly schemaRoundTripStable: boolean;
+}
+export declare const deterministicButtonInitialState: DeterministicButtonState;
+export declare function stepDeterministicButton(state: DeterministicButtonState, down: boolean, frame: number): DeterministicButtonStep;
+export declare function runDeterministicButtonFixture(frames?: number): DeterministicButtonFixtureResult;
+export declare function runDeterministicDescriptorButtonFixture(frames?: number): DeterministicDescriptorButtonFixtureResult;
+export declare function readDeterministicDescriptorButtonValue(value: CanonicalValue): boolean;

package/dist/input-button.js

@@ -0,0 +1,249 @@
+import { defaultChecksum } from './canonical.js';
+import { createSchemaArtifacts } from './schema-artifacts.js';
+export const deterministicButtonInitialState = {
+    down: false,
+    previousDown: false,
+    pressedFrame: -1,
+    releasedFrame: -1,
+};
+export function stepDeterministicButton(state, down, frame) {
+    if (!Number.isInteger(frame) || frame < 0) {
+        throw new Error('Deterministic button frame must be a non-negative integer');
+    }
+    const wasPressed = down && !state.down;
+    const wasReleased = !down && state.down;
+    const next = {
+        down,
+        previousDown: state.down,
+        pressedFrame: wasPressed ? frame : state.pressedFrame,
+        releasedFrame: wasReleased ? frame : state.releasedFrame,
+    };
+    return {
+        state: next,
+        isDown: next.down,
+        wasPressed,
+        wasReleased,
+        checksum: defaultChecksum({ frame, next, wasPressed, wasReleased }),
+    };
+}
+export function runDeterministicButtonFixture(frames = 512) {
+    let state = deterministicButtonInitialState;
+    let snapshot = state;
+    let pressedCount = 0;
+    let releasedCount = 0;
+    let heldFrames = 0;
+    let repeatedFrames = 0;
+    const transitions = [];
+    for (let frame = 0; frame < frames; frame += 1) {
+        if (frame === Math.floor(frames / 2)) {
+            snapshot = state;
+        }
+        const down = buttonDownAt(frame);
+        const step = stepDeterministicButton(state, down, frame);
+        state = step.state;
+        pressedCount += step.wasPressed ? 1 : 0;
+        releasedCount += step.wasReleased ? 1 : 0;
+        heldFrames += step.isDown ? 1 : 0;
+        repeatedFrames += step.isDown && !step.wasPressed ? 1 : 0;
+        if (step.wasPressed || step.wasReleased) {
+            transitions.push(`${frame}:${step.wasPressed ? 'pressed' : 'released'}`);
+        }
+    }
+    const checksum = defaultChecksum({ state, pressedCount, releasedCount, heldFrames, repeatedFrames, transitions });
+    let restored = snapshot;
+    let restoredPressedCount = 0;
+    let restoredReleasedCount = 0;
+    let restoredHeldFrames = 0;
+    let restoredRepeatedFrames = 0;
+    const restoredTransitions = [];
+    for (let frame = Math.floor(frames / 2); frame < frames; frame += 1) {
+        const step = stepDeterministicButton(restored, buttonDownAt(frame), frame);
+        restored = step.state;
+        restoredPressedCount += step.wasPressed ? 1 : 0;
+        restoredReleasedCount += step.wasReleased ? 1 : 0;
+        restoredHeldFrames += step.isDown ? 1 : 0;
+        restoredRepeatedFrames += step.isDown && !step.wasPressed ? 1 : 0;
+        if (step.wasPressed || step.wasReleased) {
+            restoredTransitions.push(`${frame}:${step.wasPressed ? 'pressed' : 'released'}`);
+        }
+    }
+    const prefix = replayButtonPrefix(Math.floor(frames / 2));
+    const restoredChecksum = defaultChecksum({
+        state: restored,
+        pressedCount: prefix.pressedCount + restoredPressedCount,
+        releasedCount: prefix.releasedCount + restoredReleasedCount,
+        heldFrames: prefix.heldFrames + restoredHeldFrames,
+        repeatedFrames: prefix.repeatedFrames + restoredRepeatedFrames,
+        transitions: [...prefix.transitions, ...restoredTransitions],
+    });
+    return {
+        checksum,
+        restoredChecksum,
+        rollbackEquivalent: checksum === restoredChecksum,
+        pressedCount,
+        releasedCount,
+        heldFrames,
+        repeatedFrames,
+        transitionsStable: pressedCount === releasedCount && transitions.length === pressedCount + releasedCount,
+    };
+}
+export function runDeterministicDescriptorButtonFixture(frames = 512) {
+    const artifacts = createSchemaArtifacts(buttonDescriptor());
+    const missingDefault = artifacts.deserializeInput(artifacts.serializeInput({ axis: 0 }));
+    let state = deterministicButtonInitialState;
+    let snapshot = state;
+    let pressedCount = 0;
+    let releasedCount = 0;
+    let heldFrames = 0;
+    let repeatedFrames = 0;
+    let serializedBytes = 0;
+    const transitions = [];
+    for (let frame = 0; frame < frames; frame += 1) {
+        if (frame === Math.floor(frames / 2)) {
+            snapshot = state;
+        }
+        const input = descriptorButtonInputAt(frame);
+        const serialized = artifacts.serializeInput(input);
+        const roundTrip = artifacts.deserializeInput(serialized);
+        serializedBytes += serialized.byteLength;
+        const step = stepDeterministicButton(state, buttonValue(roundTrip), frame);
+        state = step.state;
+        pressedCount += step.wasPressed ? 1 : 0;
+        releasedCount += step.wasReleased ? 1 : 0;
+        heldFrames += step.isDown ? 1 : 0;
+        repeatedFrames += step.isDown && !step.wasPressed ? 1 : 0;
+        if (step.wasPressed || step.wasReleased) {
+            transitions.push(`${frame}:${step.wasPressed ? 'pressed' : 'released'}`);
+        }
+    }
+    const checksum = defaultChecksum({ state, pressedCount, releasedCount, heldFrames, repeatedFrames, transitions });
+    const prefix = replayDescriptorButtonPrefix(Math.floor(frames / 2), artifacts);
+    let restored = snapshot;
+    let restoredPressedCount = 0;
+    let restoredReleasedCount = 0;
+    let restoredHeldFrames = 0;
+    let restoredRepeatedFrames = 0;
+    const restoredTransitions = [];
+    for (let frame = Math.floor(frames / 2); frame < frames; frame += 1) {
+        const roundTrip = artifacts.deserializeInput(artifacts.serializeInput(descriptorButtonInputAt(frame)));
+        const step = stepDeterministicButton(restored, buttonValue(roundTrip), frame);
+        restored = step.state;
+        restoredPressedCount += step.wasPressed ? 1 : 0;
+        restoredReleasedCount += step.wasReleased ? 1 : 0;
+        restoredHeldFrames += step.isDown ? 1 : 0;
+        restoredRepeatedFrames += step.isDown && !step.wasPressed ? 1 : 0;
+        if (step.wasPressed || step.wasReleased) {
+            restoredTransitions.push(`${frame}:${step.wasPressed ? 'pressed' : 'released'}`);
+        }
+    }
+    const restoredChecksum = defaultChecksum({
+        state: restored,
+        pressedCount: prefix.pressedCount + restoredPressedCount,
+        releasedCount: prefix.releasedCount + restoredReleasedCount,
+        heldFrames: prefix.heldFrames + restoredHeldFrames,
+        repeatedFrames: prefix.repeatedFrames + restoredRepeatedFrames,
+        transitions: [...prefix.transitions, ...restoredTransitions],
+    });
+    const roundTripA = artifacts.serializeInput({ axis: 1, jump: true });
+    const roundTripB = artifacts.serializeInput(artifacts.deserializeInput(roundTripA));
+    const descriptorArtifactId = artifacts.descriptor.artifactId;
+    const descriptorButtonFields = artifacts.descriptor.input.fields.filter((field) => field.kind === 'button').length;
+    const defaultApplied = buttonValue(missingDefault) === false;
+    const schemaRoundTripStable = defaultChecksum(roundTripA) === defaultChecksum(roundTripB);
+    return {
+        checksum,
+        restoredChecksum,
+        rollbackEquivalent: checksum === restoredChecksum,
+        pressedCount,
+        releasedCount,
+        heldFrames,
+        repeatedFrames,
+        transitionsStable: pressedCount === releasedCount && transitions.length === pressedCount + releasedCount,
+        descriptorArtifactId,
+        descriptorButtonFields,
+        serializedBytes,
+        defaultApplied,
+        schemaRoundTripStable,
+    };
+}
+function replayButtonPrefix(frames) {
+    let state = deterministicButtonInitialState;
+    let pressedCount = 0;
+    let releasedCount = 0;
+    let heldFrames = 0;
+    let repeatedFrames = 0;
+    const transitions = [];
+    for (let frame = 0; frame < frames; frame += 1) {
+        const step = stepDeterministicButton(state, buttonDownAt(frame), frame);
+        state = step.state;
+        pressedCount += step.wasPressed ? 1 : 0;
+        releasedCount += step.wasReleased ? 1 : 0;
+        heldFrames += step.isDown ? 1 : 0;
+        repeatedFrames += step.isDown && !step.wasPressed ? 1 : 0;
+        if (step.wasPressed || step.wasReleased) {
+            transitions.push(`${frame}:${step.wasPressed ? 'pressed' : 'released'}`);
+        }
+    }
+    return { pressedCount, releasedCount, heldFrames, repeatedFrames, transitions };
+}
+function replayDescriptorButtonPrefix(frames, artifacts) {
+    let state = deterministicButtonInitialState;
+    let pressedCount = 0;
+    let releasedCount = 0;
+    let heldFrames = 0;
+    let repeatedFrames = 0;
+    const transitions = [];
+    for (let frame = 0; frame < frames; frame += 1) {
+        const roundTrip = artifacts.deserializeInput(artifacts.serializeInput(descriptorButtonInputAt(frame)));
+        const step = stepDeterministicButton(state, buttonValue(roundTrip), frame);
+        state = step.state;
+        pressedCount += step.wasPressed ? 1 : 0;
+        releasedCount += step.wasReleased ? 1 : 0;
+        heldFrames += step.isDown ? 1 : 0;
+        repeatedFrames += step.isDown && !step.wasPressed ? 1 : 0;
+        if (step.wasPressed || step.wasReleased) {
+            transitions.push(`${frame}:${step.wasPressed ? 'pressed' : 'released'}`);
+        }
+    }
+    return { pressedCount, releasedCount, heldFrames, repeatedFrames, transitions };
+}
+function buttonDownAt(frame) {
+    const phase = frame % 16;
+    return (phase >= 2 && phase <= 6) || phase === 10 || phase === 11;
+}
+function descriptorButtonInputAt(frame) {
+    return {
+        axis: (frame % 3) - 1,
+        jump: buttonDownAt(frame),
+    };
+}
+export function readDeterministicDescriptorButtonValue(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Descriptor button input did not deserialize to a boolean jump field');
+    }
+    const record = value;
+    if (typeof record.jump !== 'boolean') {
+        throw new Error('Descriptor button input did not deserialize to a boolean jump field');
+    }
+    return record.jump;
+}
+const buttonValue = readDeterministicDescriptorButtonValue;
+function buttonDescriptor() {
+    return {
+        deterministicVersion: 'button-input@1',
+        tickRate: 60,
+        maxPlayers: 128,
+        input: {
+            id: 'button-input/v1',
+            fields: [
+                { name: 'axis', kind: 'integer', policy: 'repeat', defaultValue: 0, min: -1, max: 1, bitPacking: { bits: 2, signed: true } },
+                { name: 'jump', kind: 'button', policy: 'command', defaultValue: false, bitPacking: { bits: 1 } },
+            ],
+        },
+        state: {
+            id: 'button-state/v1',
+            fields: [{ name: 'pressed', kind: 'integer', numericMode: 'integer', checksummed: true }],
+        },
+        systems: [{ id: 'button-input' }],
+    };
+}

package/dist/input-timeline.d.ts

@@ -0,0 +1,65 @@
+import { type DeterministicSessionInputFlag } from './deterministic-session.js';
+export type DeterministicInputTimelineLane = 'human' | 'bot' | 'absent' | 'spectator' | 'late-join';
+export type DeterministicInputTimelinePrediction = 'explicit' | 'repeat-last' | 'neutral' | 'none';
+export type DeterministicInputTimelineVerification = 'confirmed' | 'replacement' | 'absent';
+export type DeterministicInputTimelineCorrection = 'none' | 'late-fill' | 'rollback-triggered';
+export interface DeterministicInputTimelineRow {
+    readonly frame: number;
+    readonly slot: number;
+    readonly lane: DeterministicInputTimelineLane;
+    readonly prediction: DeterministicInputTimelinePrediction;
+    readonly verification: DeterministicInputTimelineVerification;
+    readonly correction: DeterministicInputTimelineCorrection;
+    readonly predictedValue: number;
+    readonly verifiedValue: number;
+    readonly flags: readonly DeterministicSessionInputFlag[];
+}
+export interface DeterministicInputTimelineNegativeCases {
+    readonly validPredictionAccepted: boolean;
+    readonly inactivePredictionRejected: boolean;
+    readonly malformedValueRejected: boolean;
+    readonly duplicateIngressRejected: boolean;
+    readonly duplicateAfterRestoreRejected: boolean;
+    readonly futureIngressRejected: boolean;
+    readonly staleIngressRejected: boolean;
+    readonly spectatorIngressRejected: boolean;
+    readonly badSenderRejected: boolean;
+}
+export interface DeterministicInputTimelineReport {
+    readonly schemaVersion: 1;
+    readonly kind: 'deterministic-input-timeline';
+    readonly result: 'pass' | 'fail';
+    readonly players: number;
+    readonly frames: number;
+    readonly seed: number;
+    readonly rowCount: number;
+    readonly rowHash: string;
+    readonly sampledRows: readonly DeterministicInputTimelineRow[];
+    readonly rows?: readonly DeterministicInputTimelineRow[];
+    readonly counts: Readonly<Record<string, number>>;
+    readonly negativeCases: DeterministicInputTimelineNegativeCases;
+    readonly replayVerified: boolean;
+    readonly replayChecksum: string;
+    readonly finalVerifiedChecksum: string;
+    readonly invariants: Readonly<Record<string, boolean>>;
+    readonly checksum: string;
+}
+export interface DeterministicInputTimelineOptions {
+    readonly players: number;
+    readonly frames: number;
+    readonly seed: number;
+    readonly includeRows?: boolean;
+    readonly sampleLimit?: number;
+}
+export interface DeterministicInputTimelineAccumulatorState {
+    readonly sum: number;
+    readonly frames: number;
+    readonly activeInputs: number;
+}
+export declare function runDeterministicInputTimelineFixture(options: DeterministicInputTimelineOptions): DeterministicInputTimelineReport;
+export declare function evaluateDeterministicInputTimelineResult(invariantChecks: readonly boolean[]): 'pass' | 'fail';
+export declare function accumulateDeterministicInputTimelineState(state: Partial<DeterministicInputTimelineAccumulatorState>, input: Partial<{
+    readonly sum: number;
+    readonly active: number;
+}>): DeterministicInputTimelineAccumulatorState;
+export declare function sortDeterministicInputTimelineFlags(flags: readonly DeterministicSessionInputFlag[]): readonly DeterministicSessionInputFlag[];