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

package/dist/session-snapshot.d.ts

@@ -0,0 +1,95 @@
+import type { EncodedInput } from './input-authority.js';
+import type { DeterministicLocalAuthoritySnapshotIdentity, DeterministicLocalAuthoritySnapshotTransfer } from './local-authority-wire.js';
+/**
+ * Session-state snapshot payload + transfer plumbing for snapshot late-join (§6 M5.5).
+ *
+ * The frozen `rdm-local-authority/v1` wire reserved `snapshot-request/offer/chunk/complete`
+ * envelope kinds whose `snapshotBytes` field is an opaque string. This module defines what
+ * Syncplay puts INSIDE that string — a versioned envelope around the game's opaque serialized
+ * state — plus a transfer builder/collector shared by the authority room (which stores,
+ * validates, and forwards snapshots without ever running game code) and the networked client
+ * (donor and joiner roles). No changes to the frozen wire files: transfers are built as plain
+ * `DeterministicLocalAuthoritySnapshotTransfer` data and ride the existing envelope creators.
+ */
+export interface DeterministicStateSnapshot {
+    readonly v: 1;
+    /** The confirmed tick this snapshot proves (checksum-report tick convention). */
+    readonly tick: number;
+    /** The session frame holding the state AFTER stepping `tick` — always tick + 1. */
+    readonly sessionFrame: number;
+    /** base64 of the game's opaque serialized state (its serializeState seam). */
+    readonly stateBytes: string;
+    readonly randomState: number;
+    /** defaultChecksum of the state at `sessionFrame` — comparable to checksum-reports at `tick`. */
+    readonly stateChecksum: string;
+    /** Confirmed inputs at `tick` — seeds the joiner's last-confirmed prediction inputs. */
+    readonly confirmedInputs: readonly EncodedInput[];
+}
+/**
+ * Room-level snapshot identity, computable by the game-agnostic authority AND
+ * every client from the session-start parameters — the `descriptorHash` on
+ * snapshot wire envelopes. Game-build identity (`schemaHash`) is layered on
+ * top by clients, which know their schema ids; the authority passes it through
+ * opaquely.
+ */
+export declare function deterministicRoomDescriptorHash(params: {
+    readonly seed: number;
+    readonly playerCount: number;
+    readonly tickRateHz: number;
+    readonly hardToleranceTicks: number;
+}): string;
+export type DeterministicStateSnapshotDecodeRejection = 'invalid-json' | 'not-a-snapshot' | 'unsupported-snapshot-version' | 'malformed-snapshot';
+export type DeterministicStateSnapshotDecodeResult = {
+    readonly ok: true;
+    readonly snapshot: DeterministicStateSnapshot;
+} | {
+    readonly ok: false;
+    readonly reason: DeterministicStateSnapshotDecodeRejection;
+};
+export declare function encodeDeterministicStateSnapshot(snapshot: DeterministicStateSnapshot): string;
+export declare function decodeDeterministicStateSnapshot(text: string): DeterministicStateSnapshotDecodeResult;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(text: string): Uint8Array;
+export declare const DEFAULT_SNAPSHOT_CHUNK_SIZE = 262144;
+export declare const DEFAULT_MAX_SNAPSHOT_BYTES = 4194304;
+export interface CreateSnapshotTransferOptions {
+    readonly identity: DeterministicLocalAuthoritySnapshotIdentity;
+    /** Session frame of the snapshot (tick + 1) — the wire's meaning of transfer `frame`. */
+    readonly frame: number;
+    readonly transferId: string;
+    readonly chunkSize?: number;
+}
+export declare function createSnapshotTransferFromBytes(snapshotBytes: string, options: CreateSnapshotTransferOptions): DeterministicLocalAuthoritySnapshotTransfer;
+export interface CollectedSnapshotTransfer {
+    readonly transferId: string;
+    readonly identity: DeterministicLocalAuthoritySnapshotIdentity;
+    /** Session frame (tick + 1) as offered on the wire. */
+    readonly frame: number;
+    readonly snapshotChecksum: string;
+    readonly snapshotBytes: string;
+}
+export type SnapshotTransferStepResult = {
+    readonly accepted: true;
+} | {
+    readonly accepted: false;
+    readonly reason: SnapshotTransferRejection;
+};
+export type SnapshotTransferCompleteResult = {
+    readonly accepted: true;
+    readonly transfer: CollectedSnapshotTransfer;
+} | {
+    readonly accepted: false;
+    readonly reason: SnapshotTransferRejection;
+};
+export type SnapshotTransferRejection = 'malformed-snapshot-offer' | 'snapshot-too-large' | 'unknown-snapshot-transfer' | 'snapshot-chunk-index-out-of-range' | 'duplicate-snapshot-chunk' | 'snapshot-chunk-checksum-mismatch' | 'malformed-snapshot-chunk' | 'malformed-snapshot-complete' | 'missing-snapshot-chunk' | 'snapshot-byte-length-mismatch' | 'snapshot-transfer-checksum-mismatch';
+export interface SnapshotTransferCollector {
+    offer(payload: Readonly<Record<string, unknown>>): SnapshotTransferStepResult;
+    chunk(payload: Readonly<Record<string, unknown>>): SnapshotTransferStepResult;
+    complete(payload: Readonly<Record<string, unknown>>): SnapshotTransferCompleteResult;
+    abort(transferId: string): void;
+    readonly pendingTransferIds: readonly string[];
+}
+export interface SnapshotTransferCollectorOptions {
+    readonly maxSnapshotBytes?: number;
+}
+export declare function createSnapshotTransferCollector(options?: SnapshotTransferCollectorOptions): SnapshotTransferCollector;

package/dist/session-snapshot.js

@@ -0,0 +1,255 @@
+import { canonicalStringify, cloneCanonical, defaultChecksum } from './canonical.js';
+/**
+ * Room-level snapshot identity, computable by the game-agnostic authority AND
+ * every client from the session-start parameters — the `descriptorHash` on
+ * snapshot wire envelopes. Game-build identity (`schemaHash`) is layered on
+ * top by clients, which know their schema ids; the authority passes it through
+ * opaquely.
+ */
+export function deterministicRoomDescriptorHash(params) {
+    return defaultChecksum({
+        kind: 'rdm-room-descriptor',
+        seed: params.seed,
+        playerCount: params.playerCount,
+        tickRateHz: params.tickRateHz,
+        hardToleranceTicks: params.hardToleranceTicks,
+    });
+}
+export function encodeDeterministicStateSnapshot(snapshot) {
+    return canonicalStringify(snapshot);
+}
+export function decodeDeterministicStateSnapshot(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: 'invalid-json' };
+    }
+    if (!isRecord(parsed)) {
+        return { ok: false, reason: 'not-a-snapshot' };
+    }
+    if (parsed.v !== 1) {
+        return { ok: false, reason: 'unsupported-snapshot-version' };
+    }
+    if (!isNonNegativeInt(parsed.tick) ||
+        !isNonNegativeInt(parsed.sessionFrame) ||
+        parsed.sessionFrame !== parsed.tick + 1 ||
+        typeof parsed.stateBytes !== 'string' ||
+        !Number.isInteger(parsed.randomState) ||
+        typeof parsed.stateChecksum !== 'string' ||
+        parsed.stateChecksum.length === 0 ||
+        !Array.isArray(parsed.confirmedInputs)) {
+        return { ok: false, reason: 'malformed-snapshot' };
+    }
+    return {
+        ok: true,
+        snapshot: {
+            v: 1,
+            tick: parsed.tick,
+            sessionFrame: parsed.sessionFrame,
+            stateBytes: parsed.stateBytes,
+            randomState: parsed.randomState,
+            stateChecksum: parsed.stateChecksum,
+            confirmedInputs: cloneCanonical(parsed.confirmedInputs),
+        },
+    };
+}
+// ── base64 (browser-safe: no Buffer, no atob dependency) ──
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const BASE64_LOOKUP = new Map([...BASE64_ALPHABET].map((char, index) => [char, index]));
+export function bytesToBase64(bytes) {
+    let out = '';
+    for (let index = 0; index < bytes.length; index += 3) {
+        const b0 = bytes[index];
+        const b1 = index + 1 < bytes.length ? bytes[index + 1] : 0;
+        const b2 = index + 2 < bytes.length ? bytes[index + 2] : 0;
+        out += BASE64_ALPHABET[b0 >> 2];
+        out += BASE64_ALPHABET[((b0 & 0x03) << 4) | (b1 >> 4)];
+        out += index + 1 < bytes.length ? BASE64_ALPHABET[((b1 & 0x0f) << 2) | (b2 >> 6)] : '=';
+        out += index + 2 < bytes.length ? BASE64_ALPHABET[b2 & 0x3f] : '=';
+    }
+    return out;
+}
+export function base64ToBytes(text) {
+    if (text.length % 4 !== 0) {
+        throw new Error('base64 length must be a multiple of 4');
+    }
+    const padding = text.endsWith('==') ? 2 : text.endsWith('=') ? 1 : 0;
+    const byteLength = (text.length / 4) * 3 - padding;
+    const bytes = new Uint8Array(byteLength);
+    let byteIndex = 0;
+    for (let index = 0; index < text.length; index += 4) {
+        const values = [];
+        for (let offset = 0; offset < 4; offset += 1) {
+            const char = text[index + offset];
+            if (char === '=') {
+                if (index + 4 < text.length || offset < 2) {
+                    throw new Error('base64 padding is only valid at the end');
+                }
+                values.push(0);
+                continue;
+            }
+            const value = BASE64_LOOKUP.get(char);
+            if (value === undefined) {
+                throw new Error(`invalid base64 character ${JSON.stringify(char)}`);
+            }
+            values.push(value);
+        }
+        const triple = (values[0] << 18) | (values[1] << 12) | (values[2] << 6) | values[3];
+        if (byteIndex < byteLength)
+            bytes[byteIndex++] = (triple >> 16) & 0xff;
+        if (byteIndex < byteLength)
+            bytes[byteIndex++] = (triple >> 8) & 0xff;
+        if (byteIndex < byteLength)
+            bytes[byteIndex++] = triple & 0xff;
+    }
+    return bytes;
+}
+// ── transfer builder (raw bytes → frozen wire transfer shape) ──
+export const DEFAULT_SNAPSHOT_CHUNK_SIZE = 262_144;
+export const DEFAULT_MAX_SNAPSHOT_BYTES = 4_194_304;
+export function createSnapshotTransferFromBytes(snapshotBytes, options) {
+    const chunkSize = options.chunkSize ?? DEFAULT_SNAPSHOT_CHUNK_SIZE;
+    if (!Number.isInteger(chunkSize) || chunkSize <= 0) {
+        throw new Error('Snapshot chunkSize must be a positive integer');
+    }
+    if (snapshotBytes.length === 0) {
+        throw new Error('Snapshot bytes must be non-empty');
+    }
+    const chunks = [];
+    for (let offset = 0; offset < snapshotBytes.length; offset += chunkSize) {
+        chunks.push(snapshotBytes.slice(offset, offset + chunkSize));
+    }
+    return {
+        transferId: options.transferId,
+        identity: cloneCanonical(options.identity),
+        frame: options.frame,
+        snapshotChecksum: defaultChecksum(snapshotBytes),
+        snapshotBytes,
+        chunkSize,
+        chunks,
+        chunkChecksums: chunks.map((chunk) => defaultChecksum(chunk)),
+    };
+}
+export function createSnapshotTransferCollector(options = {}) {
+    const maxSnapshotBytes = options.maxSnapshotBytes ?? DEFAULT_MAX_SNAPSHOT_BYTES;
+    const pending = new Map();
+    return {
+        offer(payload) {
+            const identity = parseIdentity(payload.identity);
+            if (typeof payload.transferId !== 'string' ||
+                payload.transferId.length === 0 ||
+                identity === undefined ||
+                !isNonNegativeInt(payload.frame) ||
+                typeof payload.snapshotChecksum !== 'string' ||
+                !isNonNegativeInt(payload.chunkCount) ||
+                payload.chunkCount < 1 ||
+                !isNonNegativeInt(payload.totalBytes) ||
+                payload.totalBytes < 1 ||
+                // Every chunk carries at least one character, so a chunkCount that
+                // exceeds totalBytes is self-contradictory (forged offer).
+                payload.chunkCount > payload.totalBytes ||
+                !isStringArray(payload.chunkChecksums) ||
+                payload.chunkChecksums.length !== payload.chunkCount) {
+                return { accepted: false, reason: 'malformed-snapshot-offer' };
+            }
+            if (payload.totalBytes > maxSnapshotBytes) {
+                return { accepted: false, reason: 'snapshot-too-large' };
+            }
+            pending.set(payload.transferId, {
+                transferId: payload.transferId,
+                identity,
+                frame: payload.frame,
+                snapshotChecksum: payload.snapshotChecksum,
+                chunkCount: payload.chunkCount,
+                totalBytes: payload.totalBytes,
+                chunkChecksums: [...payload.chunkChecksums],
+                chunks: new Map(),
+            });
+            return { accepted: true };
+        },
+        chunk(payload) {
+            if (typeof payload.transferId !== 'string') {
+                return { accepted: false, reason: 'malformed-snapshot-chunk' };
+            }
+            const transfer = pending.get(payload.transferId);
+            if (transfer === undefined) {
+                return { accepted: false, reason: 'unknown-snapshot-transfer' };
+            }
+            if (typeof payload.chunk !== 'string' || typeof payload.chunkChecksum !== 'string') {
+                return { accepted: false, reason: 'malformed-snapshot-chunk' };
+            }
+            const chunkIndex = payload.chunkIndex;
+            if (!isNonNegativeInt(chunkIndex) || chunkIndex >= transfer.chunkCount) {
+                return { accepted: false, reason: 'snapshot-chunk-index-out-of-range' };
+            }
+            if (transfer.chunks.has(chunkIndex)) {
+                return { accepted: false, reason: 'duplicate-snapshot-chunk' };
+            }
+            if (transfer.chunkChecksums[chunkIndex] !== payload.chunkChecksum ||
+                defaultChecksum(payload.chunk) !== payload.chunkChecksum) {
+                return { accepted: false, reason: 'snapshot-chunk-checksum-mismatch' };
+            }
+            transfer.chunks.set(chunkIndex, payload.chunk);
+            return { accepted: true };
+        },
+        complete(payload) {
+            if (typeof payload.transferId !== 'string') {
+                return { accepted: false, reason: 'malformed-snapshot-complete' };
+            }
+            const transfer = pending.get(payload.transferId);
+            if (transfer === undefined) {
+                return { accepted: false, reason: 'unknown-snapshot-transfer' };
+            }
+            if (transfer.chunks.size !== transfer.chunkCount) {
+                return { accepted: false, reason: 'missing-snapshot-chunk' };
+            }
+            const snapshotBytes = Array.from({ length: transfer.chunkCount }, (_, index) => transfer.chunks.get(index)).join('');
+            // A failed terminal check consumes the transfer either way — the bytes are bad.
+            pending.delete(payload.transferId);
+            if (snapshotBytes.length !== transfer.totalBytes) {
+                return { accepted: false, reason: 'snapshot-byte-length-mismatch' };
+            }
+            if (defaultChecksum(snapshotBytes) !== transfer.snapshotChecksum) {
+                return { accepted: false, reason: 'snapshot-transfer-checksum-mismatch' };
+            }
+            return {
+                accepted: true,
+                transfer: {
+                    transferId: transfer.transferId,
+                    identity: transfer.identity,
+                    frame: transfer.frame,
+                    snapshotChecksum: transfer.snapshotChecksum,
+                    snapshotBytes,
+                },
+            };
+        },
+        abort(transferId) {
+            pending.delete(transferId);
+        },
+        get pendingTransferIds() {
+            return [...pending.keys()];
+        },
+    };
+}
+function parseIdentity(value) {
+    if (!isRecord(value) || typeof value.descriptorHash !== 'string' || value.descriptorHash.length === 0) {
+        return undefined;
+    }
+    return {
+        descriptorHash: value.descriptorHash,
+        ...(typeof value.schemaHash === 'string' ? { schemaHash: value.schemaHash } : {}),
+        ...(typeof value.assetDbHash === 'string' ? { assetDbHash: value.assetDbHash } : {}),
+        ...(typeof value.configHash === 'string' ? { configHash: value.configHash } : {}),
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonNegativeInt(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}

package/dist/session-wire.d.ts

@@ -0,0 +1,89 @@
+import type { ConfirmedInputFrame, EncodedInput } from './input-authority.js';
+/**
+ * Frozen v1 session-control wire protocol for game-agnostic input-authority rooms (§8, M1).
+ *
+ * Covers the server/client roles for a live match: session-start (slot assignment + the
+ * server-owned RNG seed + tick params), clock/time-sync, input, confirmed-input (the verified
+ * tick), reconnect, spectator, and close/error. Snapshot request/offer/chunk/complete for
+ * late-join reuse the existing envelopes in `local-authority-wire.ts` (wired at M5).
+ *
+ * Both families share the `rdm-local-authority/v1` version namespace. Decoding is FAIL-CLOSED:
+ * unknown protocol, unknown version, unknown kind, malformed payload, or checksum mismatch are
+ * rejected with a reason — never silently coerced. This is a public forward-compat boundary; the
+ * discriminants below are frozen and must only be extended, never repurposed.
+ */
+export declare const deterministicSessionWireVersion = 1;
+export type DeterministicSessionRole = 'player' | 'spectator';
+export type DeterministicSessionMessage = {
+    readonly kind: 'session-start';
+    readonly slot: number;
+    readonly playerCount: number;
+    readonly seed: number;
+    readonly tickRateHz: number;
+    readonly hardToleranceTicks: number;
+    readonly role: DeterministicSessionRole;
+} | {
+    readonly kind: 'time-sync-ping';
+    readonly clientSendTick: number;
+    readonly nonce: number;
+} | {
+    readonly kind: 'time-sync-pong';
+    readonly clientSendTick: number;
+    readonly nonce: number;
+    readonly authorityTick: number;
+} | {
+    readonly kind: 'input';
+    readonly slot: number;
+    readonly tick: number;
+    readonly input: EncodedInput;
+    readonly attempt: number;
+} | {
+    readonly kind: 'confirmed-input';
+    readonly authorityTick: number;
+    readonly frames: readonly ConfirmedInputFrame[];
+} | {
+    readonly kind: 'reconnect';
+    readonly slot: number;
+    readonly resumeFromTick: number;
+} | {
+    readonly kind: 'spectator-join';
+} | {
+    readonly kind: 'checksum-report';
+    readonly slot: number;
+    readonly tick: number;
+    readonly checksum: string;
+} | {
+    /**
+     * Client → authority netcode telemetry (G8). Additive v1 extension: unknown
+     * kinds are dropped fail-closed by older decoders, so this never breaks an
+     * old authority. All fields are integers (rttMs rounded, timescale in
+     * permille) so the payload stays canonical-checksum friendly.
+     */
+    readonly kind: 'net-stats';
+    readonly slot: number;
+    readonly tick: number;
+    readonly rttMs: number;
+    readonly rollbacks: number;
+    readonly maxRollbackDepth: number;
+    readonly timescalePermille: number;
+    readonly inputDelayTicks: number;
+} | {
+    readonly kind: 'close';
+    readonly code: string;
+    readonly reason: string;
+} | {
+    readonly kind: 'error';
+    readonly code: string;
+    readonly message: string;
+};
+export type DeterministicSessionMessageKind = DeterministicSessionMessage['kind'];
+export type DeterministicSessionDecodeRejection = 'invalid-json' | 'not-an-envelope' | 'unknown-protocol' | 'unknown-version' | 'unknown-kind' | 'checksum-mismatch' | 'malformed-payload';
+export type DeterministicSessionDecodeResult = {
+    readonly ok: true;
+    readonly message: DeterministicSessionMessage;
+} | {
+    readonly ok: false;
+    readonly reason: DeterministicSessionDecodeRejection;
+};
+export declare function encodeDeterministicSessionMessage(message: DeterministicSessionMessage): string;
+export declare function decodeDeterministicSessionMessage(text: string): DeterministicSessionDecodeResult;

package/dist/session-wire.js

@@ -0,0 +1,211 @@
+import { canonicalStringify, decodeCanonicalValue, defaultChecksum } from './canonical.js';
+import { deterministicLocalAuthorityWireProtocol } from './local-authority-wire.js';
+/**
+ * Frozen v1 session-control wire protocol for game-agnostic input-authority rooms (§8, M1).
+ *
+ * Covers the server/client roles for a live match: session-start (slot assignment + the
+ * server-owned RNG seed + tick params), clock/time-sync, input, confirmed-input (the verified
+ * tick), reconnect, spectator, and close/error. Snapshot request/offer/chunk/complete for
+ * late-join reuse the existing envelopes in `local-authority-wire.ts` (wired at M5).
+ *
+ * Both families share the `rdm-local-authority/v1` version namespace. Decoding is FAIL-CLOSED:
+ * unknown protocol, unknown version, unknown kind, malformed payload, or checksum mismatch are
+ * rejected with a reason — never silently coerced. This is a public forward-compat boundary; the
+ * discriminants below are frozen and must only be extended, never repurposed.
+ */
+export const deterministicSessionWireVersion = 1;
+const sessionMessageKinds = new Set([
+    'session-start',
+    'time-sync-ping',
+    'time-sync-pong',
+    'input',
+    'confirmed-input',
+    'reconnect',
+    'spectator-join',
+    'checksum-report',
+    'net-stats',
+    'close',
+    'error',
+]);
+export function encodeDeterministicSessionMessage(message) {
+    const { kind, ...rest } = message;
+    const payload = rest;
+    const envelope = {
+        protocol: deterministicLocalAuthorityWireProtocol,
+        v: deterministicSessionWireVersion,
+        kind,
+        payload,
+        checksum: sessionChecksum(kind, payload),
+    };
+    return canonicalStringify(envelope);
+}
+export function decodeDeterministicSessionMessage(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: 'invalid-json' };
+    }
+    if (!isRecord(parsed)) {
+        return { ok: false, reason: 'not-an-envelope' };
+    }
+    if (parsed.protocol !== deterministicLocalAuthorityWireProtocol) {
+        return { ok: false, reason: 'unknown-protocol' };
+    }
+    if (parsed.v !== deterministicSessionWireVersion) {
+        return { ok: false, reason: 'unknown-version' };
+    }
+    if (typeof parsed.kind !== 'string' || !sessionMessageKinds.has(parsed.kind)) {
+        return { ok: false, reason: 'unknown-kind' };
+    }
+    const kind = parsed.kind;
+    if (!isRecord(parsed.payload)) {
+        return { ok: false, reason: 'malformed-payload' };
+    }
+    // Symmetry with encode: the encoder checksummed the LIVE payload value and
+    // then canonical-encoded it, so sentinel values (-0, NaN, ±Infinity,
+    // undefined, bigint, Map/Set/typed arrays) sit on the wire as literal
+    // `{"$rdm":…}` objects. Decode them back to real values BEFORE recomputing
+    // the checksum — hashing the raw parse output would trip canonicalize's
+    // reserved-key guard and throw out of a decoder whose contract is
+    // fail-closed. Any malformed/hostile `$rdm` literal lands in the catch.
+    let payload;
+    let expectedChecksum;
+    try {
+        const decoded = decodeCanonicalValue(parsed.payload);
+        if (!isRecord(decoded)) {
+            return { ok: false, reason: 'malformed-payload' };
+        }
+        payload = decoded;
+        expectedChecksum = sessionChecksum(kind, payload);
+    }
+    catch {
+        return { ok: false, reason: 'malformed-payload' };
+    }
+    if (parsed.checksum !== expectedChecksum) {
+        return { ok: false, reason: 'checksum-mismatch' };
+    }
+    const message = parseSessionPayload(kind, payload);
+    if (message === undefined) {
+        return { ok: false, reason: 'malformed-payload' };
+    }
+    return { ok: true, message };
+}
+function parseSessionPayload(kind, payload) {
+    switch (kind) {
+        case 'session-start':
+            if (isInt(payload.slot) &&
+                isInt(payload.playerCount) &&
+                isInt(payload.seed) &&
+                isFiniteNumber(payload.tickRateHz) &&
+                isInt(payload.hardToleranceTicks) &&
+                isRole(payload.role)) {
+                return {
+                    kind,
+                    slot: payload.slot,
+                    playerCount: payload.playerCount,
+                    seed: payload.seed,
+                    tickRateHz: payload.tickRateHz,
+                    hardToleranceTicks: payload.hardToleranceTicks,
+                    role: payload.role,
+                };
+            }
+            return undefined;
+        case 'time-sync-ping':
+            if (isInt(payload.clientSendTick) && isInt(payload.nonce)) {
+                return { kind, clientSendTick: payload.clientSendTick, nonce: payload.nonce };
+            }
+            return undefined;
+        case 'time-sync-pong':
+            if (isInt(payload.clientSendTick) && isInt(payload.nonce) && isInt(payload.authorityTick)) {
+                return { kind, clientSendTick: payload.clientSendTick, nonce: payload.nonce, authorityTick: payload.authorityTick };
+            }
+            return undefined;
+        case 'input':
+            if (isInt(payload.slot) && isInt(payload.tick) && isInt(payload.attempt) && payload.input !== undefined) {
+                return { kind, slot: payload.slot, tick: payload.tick, input: payload.input, attempt: payload.attempt };
+            }
+            return undefined;
+        case 'confirmed-input':
+            if (isInt(payload.authorityTick) && isConfirmedFrameArray(payload.frames)) {
+                return { kind, authorityTick: payload.authorityTick, frames: payload.frames };
+            }
+            return undefined;
+        case 'reconnect':
+            if (isInt(payload.slot) && isInt(payload.resumeFromTick)) {
+                return { kind, slot: payload.slot, resumeFromTick: payload.resumeFromTick };
+            }
+            return undefined;
+        case 'spectator-join':
+            return { kind };
+        case 'checksum-report':
+            if (isInt(payload.slot) && isInt(payload.tick) && typeof payload.checksum === 'string') {
+                return { kind, slot: payload.slot, tick: payload.tick, checksum: payload.checksum };
+            }
+            return undefined;
+        case 'net-stats':
+            if (isInt(payload.slot) &&
+                isInt(payload.tick) &&
+                isInt(payload.rttMs) &&
+                isInt(payload.rollbacks) &&
+                isInt(payload.maxRollbackDepth) &&
+                isInt(payload.timescalePermille) &&
+                isInt(payload.inputDelayTicks)) {
+                return {
+                    kind,
+                    slot: payload.slot,
+                    tick: payload.tick,
+                    rttMs: payload.rttMs,
+                    rollbacks: payload.rollbacks,
+                    maxRollbackDepth: payload.maxRollbackDepth,
+                    timescalePermille: payload.timescalePermille,
+                    inputDelayTicks: payload.inputDelayTicks,
+                };
+            }
+            return undefined;
+        case 'close':
+            if (typeof payload.code === 'string' && typeof payload.reason === 'string') {
+                return { kind, code: payload.code, reason: payload.reason };
+            }
+            return undefined;
+        case 'error':
+            if (typeof payload.code === 'string' && typeof payload.message === 'string') {
+                return { kind, code: payload.code, message: payload.message };
+            }
+            return undefined;
+        default:
+            return assertNever(kind);
+    }
+}
+function sessionChecksum(kind, payload) {
+    return String(defaultChecksum({ protocol: deterministicLocalAuthorityWireProtocol, v: deterministicSessionWireVersion, kind, payload }));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isInt(value) {
+    return typeof value === 'number' && Number.isInteger(value);
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isRole(value) {
+    return value === 'player' || value === 'spectator';
+}
+function isConfirmedFrameArray(value) {
+    // The codec is stateless (it does not know playerCount), so it cannot check inputs.length — the
+    // consumer validates that against its own slot count. It CAN reject a frame whose substituted-slot
+    // indices are not integers (a string index survives JSON.parse and would corrupt slot handling).
+    return (Array.isArray(value) &&
+        value.every((frame) => isRecord(frame) &&
+            isInt(frame.tick) &&
+            Array.isArray(frame.inputs) &&
+            Array.isArray(frame.substitutedSlots) &&
+            frame.substitutedSlots.every((slot) => isInt(slot)) &&
+            typeof frame.checksum === 'string'));
+}
+function assertNever(value) {
+    void value;
+    return undefined;
+}

package/dist/signals.d.ts

@@ -0,0 +1,31 @@
+export interface DeterministicSignal<TPayload = Readonly<Record<string, boolean | number | string>>> {
+    readonly frame: number;
+    readonly type: string;
+    readonly payload: TPayload;
+}
+export interface DeterministicSignalSubscription<TState, TPayload = Readonly<Record<string, boolean | number | string>>> {
+    readonly id: string;
+    readonly type: string;
+    readonly order: number;
+    handle(state: Readonly<TState>, signal: DeterministicSignal<TPayload>): TState;
+}
+export interface DeterministicSignalBusSnapshot<TPayload = Readonly<Record<string, boolean | number | string>>> {
+    readonly emitted: readonly DeterministicSignal<TPayload>[];
+    readonly dispatched: readonly DeterministicSignal<TPayload>[];
+    readonly sequence: number;
+}
+export interface DeterministicSignalBus<TState, TPayload = Readonly<Record<string, boolean | number | string>>> {
+    emit(signal: DeterministicSignal<TPayload>): void;
+    dispatch(state: Readonly<TState>, frame: number): TState;
+    snapshot(): DeterministicSignalBusSnapshot<TPayload>;
+    restore(snapshot: DeterministicSignalBusSnapshot<TPayload>): void;
+}
+export interface DeterministicSignalFixtureResult {
+    readonly checksum: string;
+    readonly restoredChecksum: string;
+    readonly dispatchedSignals: number;
+    readonly subscriptionOrderStable: boolean;
+    readonly rollbackEquivalent: boolean;
+}
+export declare function createDeterministicSignalBus<TState, TPayload = Readonly<Record<string, boolean | number | string>>>(subscriptions: readonly DeterministicSignalSubscription<TState, TPayload>[]): DeterministicSignalBus<TState, TPayload>;
+export declare function runDeterministicSignalFixture(): DeterministicSignalFixtureResult;