@series-inc/rundot-syncplay 5.26.0-beta.9 → 5.26.0

package/dist/authority-room.d.ts

@@ -179,6 +179,8 @@ export interface AuthorityRoomNetcodeStats {
     readonly confirmedThrough: number;
     /** Ticks in which each slot's input had to be substituted (cumulative). */
     readonly substitutedTicksBySlot: Readonly<Record<number, number>>;
+    /** Slots with a seated player. Empty slots substitute every tick by design. */
+    readonly occupiedSlots: readonly number[];
     readonly clientStats: Readonly<Record<number, AuthorityRoomClientNetStats>>;
     /** Command requests dropped for seat, size, rate, sequence, or stale generation. */
     readonly rejectedCommands: number;
@@ -239,6 +241,14 @@ export interface DeterministicAuthorityRoom {
      * ticks, so this is idempotent.
      */
     onPlayerReconnected(playerId: string): void;
+    /**
+     * A player's transport dropped and their seat entered the host's grace
+     * window. The slot stays reserved and keeps being substituted, so release
+     * the input they were holding — otherwise a player who drops mid-movement
+     * keeps moving until the grace window expires. Safe to call for a player
+     * with no slot (spectator, unknown id).
+     */
+    onPlayerDisconnected(playerId: string): void;
     /** Advance the authority by one server tick and broadcast newly-confirmed frames. */
     onTick(): void;
     /**

package/dist/authority-room.js

@@ -351,6 +351,11 @@ export function createDeterministicAuthorityRoom(transport, config) {
         sendCatchUpTo(playerId, plan, 'join');
         return true;
     }
+    function onPlayerDisconnected(playerId) {
+        const slot = slotByPlayer.get(playerId);
+        if (slot !== undefined)
+            authority.neutralizeSlot(slot);
+    }
     function onPlayerReconnected(playerId) {
         // A spectator reconnect is a full re-greet: its timeline may have forked
         // arbitrarily far and it holds no slot the redundancy window protects.
@@ -779,6 +784,10 @@ export function createDeterministicAuthorityRoom(transport, config) {
         // departed player's input; their slot stays reserved because `assignedSlots` never decreases,
         // so the authority substitutes for it rather than handing the number to a new joiner.
         const slot = slotByPlayer.get(playerId);
+        // The slot stays reserved and keeps being substituted (see above), so
+        // release the departing player's last held input.
+        if (slot !== undefined)
+            authority.neutralizeSlot(slot);
         slotByPlayer.delete(playerId);
         if (slot !== undefined)
             secretAuthority?.onPlayerLeft(playerId, slot);
@@ -853,6 +862,7 @@ export function createDeterministicAuthorityRoom(transport, config) {
         onPlayerSecretMessage,
         onPlayerLeave,
         onPlayerReconnected,
+        onPlayerDisconnected,
         onTick,
         snapshot() {
             return {
@@ -899,6 +909,7 @@ export function createDeterministicAuthorityRoom(transport, config) {
             return {
                 confirmedThrough: authority.confirmedThrough,
                 substitutedTicksBySlot: Object.fromEntries(substitutedTicksBySlot),
+                occupiedSlots: [...slotByPlayer.values()].sort((a, b) => a - b),
                 clientStats: Object.fromEntries(clientNetStatsBySlot),
                 rejectedCommands,
                 rejectedReconfigures,

package/dist/browser.d.ts

@@ -35,7 +35,7 @@ export { createDeterministicDescriptorBinarySchema, generateSchemaBinarySource,
 export { createDeterministicBinarySerializer, deterministicDslMaxPlayers, parseDeterministicSchemaDsl, stableDeterministicDslSchemaJson } from './schema-dsl-binary.js';
 export { createSyncplaySession } from './sdk-session.js';
 export { createSessionFromPromotionSnapshot, exportPromotionSnapshot } from './session-promotion.js';
-export { base64ToBytes, bytesToBase64, createSnapshotTransferCollector, createSnapshotTransferFromBytes, decodeDeterministicStateSnapshot, DEFAULT_MAX_SNAPSHOT_BYTES, DEFAULT_SNAPSHOT_CHUNK_SIZE, deterministicRoomDescriptorHash, encodeDeterministicStateSnapshot } from './session-snapshot.js';
+export { base64ToBytes, bytesToBase64, createSnapshotTransferCollector, createSnapshotTransferFromBytes, decodeDeterministicStateSnapshot, DEFAULT_MAX_SNAPSHOT_BYTES, DEFAULT_SNAPSHOT_CHUNK_SIZE, deterministicRoomDescriptorHash, encodeDeterministicStateSnapshot, MAX_JSON_ESCAPE_EXPANSION, SNAPSHOT_CHUNK_ENVELOPE_OVERHEAD_BYTES } from './session-snapshot.js';
 export { decodeDeterministicSessionMessage, deterministicSessionWireVersion, encodeDeterministicSessionMessage } from './session-wire.js';
 export { createDeterministicSignalBus } from './signals.js';
 export { createDeterministicSparseSet } from './sparse-set.js';

package/dist/browser.js

@@ -36,7 +36,7 @@ export { createDeterministicDescriptorBinarySchema, generateSchemaBinarySource,
 export { createDeterministicBinarySerializer, deterministicDslMaxPlayers, parseDeterministicSchemaDsl, stableDeterministicDslSchemaJson } from './schema-dsl-binary.js';
 export { createSyncplaySession } from './sdk-session.js';
 export { createSessionFromPromotionSnapshot, exportPromotionSnapshot } from './session-promotion.js';
-export { base64ToBytes, bytesToBase64, createSnapshotTransferCollector, createSnapshotTransferFromBytes, decodeDeterministicStateSnapshot, DEFAULT_MAX_SNAPSHOT_BYTES, DEFAULT_SNAPSHOT_CHUNK_SIZE, deterministicRoomDescriptorHash, encodeDeterministicStateSnapshot } from './session-snapshot.js';
+export { base64ToBytes, bytesToBase64, createSnapshotTransferCollector, createSnapshotTransferFromBytes, decodeDeterministicStateSnapshot, DEFAULT_MAX_SNAPSHOT_BYTES, DEFAULT_SNAPSHOT_CHUNK_SIZE, deterministicRoomDescriptorHash, encodeDeterministicStateSnapshot, MAX_JSON_ESCAPE_EXPANSION, SNAPSHOT_CHUNK_ENVELOPE_OVERHEAD_BYTES } from './session-snapshot.js';
 export { decodeDeterministicSessionMessage, deterministicSessionWireVersion, encodeDeterministicSessionMessage } from './session-wire.js';
 export { createDeterministicSignalBus } from './signals.js';
 export { createDeterministicSparseSet } from './sparse-set.js';

package/dist/dev-authority-room.js

@@ -1,5 +1,5 @@
 import { createDeterministicAuthorityRoom, } from './authority-room.js';
-import { SYSTEM_MSG_RECONNECTED } from '@series-inc/rundot-game-sdk/mp-server';
+import { SYSTEM_MSG_DISCONNECTED, SYSTEM_MSG_RECONNECTED } from '@series-inc/rundot-game-sdk/mp-server';
 import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, sign } from 'node:crypto';
 import { validateSyncplaySecretSystemsConfig } from './secret-config.js';
 import { assertKinetixRuntimeIdentity, kinetixSessionConfigDigest, } from '@series-inc/rundot-syncplay/core/runtime';
@@ -138,6 +138,13 @@ export class DevSyncplayAuthorityRoom {
                 this.room.onPlayerReconnected(playerId);
                 return;
             }
+            // The dev server already emits this on socket loss. Handle it so local
+            // play matches production: a player who drops mid-movement stops instead
+            // of having their held input repeated through the grace window.
+            if (msgType === SYSTEM_MSG_DISCONNECTED) {
+                this.room.onPlayerDisconnected(playerId);
+                return;
+            }
             if (msgType === SECRET_MSG_TYPE) {
                 const envelope = typeof data === 'string' ? data : JSON.stringify(data);
                 this.room.onPlayerSecretMessage(playerId, envelope);

package/dist/index.d.ts

@@ -44,7 +44,7 @@ export { withRuntimeDeterminismGuards } from './runtime-guards.js';
 export { createDeterministicDescriptorBinarySchema, generateSchemaBinarySource, generateSchemaTypes, proveSchemaBinaryRoundTrip } from './schema-codegen.js';
 export { createDeterministicBinarySerializer, deterministicDslMaxPlayers, parseDeterministicSchemaDsl, stableDeterministicDslSchemaJson } from './schema-dsl-binary.js';
 export { createSyncplaySession } from './sdk-session.js';
-export { base64ToBytes, bytesToBase64, createSnapshotTransferCollector, createSnapshotTransferFromBytes, decodeDeterministicStateSnapshot, DEFAULT_MAX_SNAPSHOT_BYTES, DEFAULT_SNAPSHOT_CHUNK_SIZE, deterministicRoomDescriptorHash, encodeDeterministicStateSnapshot } from './session-snapshot.js';
+export { base64ToBytes, bytesToBase64, createSnapshotTransferCollector, createSnapshotTransferFromBytes, decodeDeterministicStateSnapshot, DEFAULT_MAX_SNAPSHOT_BYTES, DEFAULT_SNAPSHOT_CHUNK_SIZE, deterministicRoomDescriptorHash, encodeDeterministicStateSnapshot, MAX_JSON_ESCAPE_EXPANSION, SNAPSHOT_CHUNK_ENVELOPE_OVERHEAD_BYTES } from './session-snapshot.js';
 export { decodeDeterministicSessionMessage, deterministicSessionWireVersion, encodeDeterministicSessionMessage } from './session-wire.js';
 export { createDeterministicSignalBus } from './signals.js';
 export { createDeterministicSparseSet } from './sparse-set.js';

package/dist/index.js

@@ -45,7 +45,7 @@ export { withRuntimeDeterminismGuards } from './runtime-guards.js';
 export { createDeterministicDescriptorBinarySchema, generateSchemaBinarySource, generateSchemaTypes, proveSchemaBinaryRoundTrip } from './schema-codegen.js';
 export { createDeterministicBinarySerializer, deterministicDslMaxPlayers, parseDeterministicSchemaDsl, stableDeterministicDslSchemaJson } from './schema-dsl-binary.js';
 export { createSyncplaySession } from './sdk-session.js';
-export { base64ToBytes, bytesToBase64, createSnapshotTransferCollector, createSnapshotTransferFromBytes, decodeDeterministicStateSnapshot, DEFAULT_MAX_SNAPSHOT_BYTES, DEFAULT_SNAPSHOT_CHUNK_SIZE, deterministicRoomDescriptorHash, encodeDeterministicStateSnapshot } from './session-snapshot.js';
+export { base64ToBytes, bytesToBase64, createSnapshotTransferCollector, createSnapshotTransferFromBytes, decodeDeterministicStateSnapshot, DEFAULT_MAX_SNAPSHOT_BYTES, DEFAULT_SNAPSHOT_CHUNK_SIZE, deterministicRoomDescriptorHash, encodeDeterministicStateSnapshot, MAX_JSON_ESCAPE_EXPANSION, SNAPSHOT_CHUNK_ENVELOPE_OVERHEAD_BYTES } from './session-snapshot.js';
 export { decodeDeterministicSessionMessage, deterministicSessionWireVersion, encodeDeterministicSessionMessage } from './session-wire.js';
 export { createDeterministicSignalBus } from './signals.js';
 export { createDeterministicSparseSet } from './sparse-set.js';

package/dist/input-authority.d.ts

@@ -83,6 +83,14 @@ export interface InputAuthority {
      * frontier; a no-op at or below the current earliest retained tick.
      */
     pruneConfirmedBefore(tick: number): void;
+    /**
+     * Forget a slot's last confirmed input so later substitutions fall back to
+     * `neutralInput`. Call this when a slot's player disconnects or leaves: the
+     * slot stays reserved and keeps being substituted, so without this the
+     * authority repeats whatever they were holding when they dropped for the
+     * rest of the match. Out-of-roster slots are ignored.
+     */
+    neutralizeSlot(slot: number): void;
     stats(): InputAuthorityStats;
 }
 export declare function createInputAuthority(config: InputAuthorityConfig): InputAuthority;

package/dist/input-authority.js

@@ -185,6 +185,19 @@ export function createInputAuthority(config) {
             }
             earliestRetained = tick;
         },
+        neutralizeSlot(slot) {
+            if (!Number.isInteger(slot) || slot < 0 || slot >= playerCount)
+                return;
+            lastConfirmedInput[slot] = config.neutralInput;
+            // Resetting the last-confirmed value is not enough on its own: clients
+            // queue ahead by `inputDelayTicks`, so a dropping player usually has
+            // future ticks already buffered. `confirmTick` reassigns
+            // `lastConfirmedInput` from any submitted input, so leaving those in
+            // place would resurrect the held input on the very next confirm.
+            for (const slots of pending.values()) {
+                slots[slot] = undefined;
+            }
+        },
         stats() {
             return { confirmedTicks, substitutedInputs, droppedLateInputs, rejectedFutureInputs };
         },

package/dist/networked-client.d.ts

@@ -142,6 +142,14 @@ export interface NetworkedSyncplayClientNetStats {
     readonly droppedConfirmedPresentationFrames: number;
     /** Commands this client refused to send (oversized payload). */
     readonly rejectedCommands: number;
+    /**
+     * Confirmed ticks in which THIS client's own input was substituted because it
+     * did not reach the authority in time. Monotonic within a session and reset on
+     * session-start. Counted per applied tick, so a batch of confirmations that
+     * substitutes some ticks and not the last one still reports every one — a
+     * consumer reading `confirmedPlayerPresence` alone sees only the final tick.
+     */
+    readonly ownInputSubstitutions: number;
 }
 export type NetworkedSyncplaySlotPresence = 'human' | 'substituted' | 'empty' | 'unknown';
 export interface ConfirmedSyncplayPresentationFrame<Projection> {

package/dist/networked-client.js

@@ -282,6 +282,7 @@ export function createNetworkedSyncplayClient(options) {
     let sessionGeneration = 0;
     let commandSequence = 0;
     let droppedConfirmedPresentationFrames = 0;
+    let ownInputSubstitutions = 0;
     let rejectedCommands = 0;
     const ephemeralHandlers = new Set();
     let pendingEphemeral;
@@ -427,6 +428,7 @@ export function createNetworkedSyncplayClient(options) {
             confirmed.clear();
             reportedTicks.length = 0;
             lastAutoReportedTick = -1;
+            ownInputSubstitutions = 0;
             transferCollector = createSnapshotTransferCollector(snapshotCollectorOptions);
             outgoingTransferQueue.length = 0;
             tickRateHz = message.tickRateHz;
@@ -912,6 +914,11 @@ export function createNetworkedSyncplayClient(options) {
             for (let playerSlot = 0; playerSlot < playerCount; playerSlot += 1) {
                 lastConfirmedBySlot[playerSlot] = confInputs[playerSlot];
             }
+            // Per APPLIED tick, not per drained batch: `confirmedPlayerPresence`
+            // latches only the last tick of a batch, so a burst that substitutes
+            // several ticks and ends on a delivered one would otherwise vanish.
+            if (slot >= 0 && confFrame.substitutedSlots.includes(slot))
+                ownInputSubstitutions += 1;
             appliedThrough = tick;
             confirmedPlayerPresence = classifyPresence(confFrame);
             const presentationEligible = presentationWasLive || (freshRoomFirstFrame && tick === 0);
@@ -1232,6 +1239,7 @@ export function createNetworkedSyncplayClient(options) {
                 maxRollbackDepth,
                 droppedConfirmedPresentationFrames,
                 rejectedCommands,
+                ownInputSubstitutions,
             };
         },
         get generation() {

package/dist/node.d.ts

@@ -19,6 +19,8 @@ export { buildMerkleTree, bytesToHex, concatBytes, constantTimeEqual, createBrow
 export type { SyncplaySecretAuthorityCrypto, SyncplaySecretBrowserCrypto } from './secret-crypto.js';
 export * from './ws-frame.js';
 export { SYNCPLAY_DETERMINISTIC_ROOM_OPTION_KEYS } from './rooms-config-keys.js';
+export { createSyncplayRuntimePin, parseSyncplayRuntimeRoomMetadata, MAX_SYNCPLAY_SESSION_CONFIG_BYTES, } from './runtime-room-metadata.js';
+export type { SyncplayRuntimeIdentity, SyncplayRuntimeRoomMetadata, ParsedSyncplayRuntimeRoomMetadata, SyncplayRuntimeConfigInput, } from './runtime-room-metadata.js';
 export type { SyncplayDeterministicRoomOptionKey } from './rooms-config-keys.js';
 export { assertCookedColliderIsRuntimeValid, cookConvexDecomposition, } from './collider-cooking.js';
 export type { ColliderCookOptions, ColliderSourceMesh, CookedCollider, CookedColliderHull, } from './collider-cooking.js';

package/dist/node.js

@@ -16,6 +16,7 @@ export * from './secret-authority.js';
 export { buildMerkleTree, bytesToHex, concatBytes, constantTimeEqual, createBrowserSyncplaySecretCrypto, hexToBytes, merkleLeafHash, merkleNodeHash, merkleProof, sha256Bytes, signedReceiptBytes, verifyHashChainReveal, verifyMerkleProof, verifySyncplaySignedReceipt, } from './secret-crypto.js';
 export * from './ws-frame.js';
 export { SYNCPLAY_DETERMINISTIC_ROOM_OPTION_KEYS } from './rooms-config-keys.js';
+export { createSyncplayRuntimePin, parseSyncplayRuntimeRoomMetadata, MAX_SYNCPLAY_SESSION_CONFIG_BYTES, } from './runtime-room-metadata.js';
 export { assertCookedColliderIsRuntimeValid, cookConvexDecomposition, } from './collider-cooking.js';
 // Dev-server deterministic room class (relocated from the game SDK). A game's
 // vite.config passes this to rundotMultiplayerPlugin({ deterministicRoomClass }).

package/dist/runtime-room-metadata.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The runtime a deterministic room simulates: engine identity plus the
+ * canonical session config (the game's rules) it was created with.
+ *
+ * This is the ONE implementation. The build mints a pin with
+ * `createSyncplayRuntimePin`, the publish path validates it, and the room
+ * server validates it again on room create — all through
+ * `parseSyncplayRuntimeRoomMetadata` below. A second copy of these rules is how
+ * a pin could pass one gate and fail another.
+ */
+export declare const MAX_SYNCPLAY_SESSION_CONFIG_BYTES: 65536;
+export interface SyncplayRuntimeIdentity {
+    readonly abiVersion: 1;
+    readonly tickRate: 10 | 20 | 30 | 60;
+    readonly inputSchemaId: string;
+    readonly stateSchemaId: string;
+    readonly deterministicVersion: string;
+    readonly engineIdentityHash: string;
+}
+/** Wire shape: `sessionConfigBytes` is canonical base64. */
+export interface SyncplayRuntimeRoomMetadata {
+    readonly runtimeIdentity: SyncplayRuntimeIdentity;
+    readonly sessionConfigBytes: string;
+    readonly sessionConfigDigest: string;
+}
+/** Parsed shape: `sessionConfigBytes` decoded. */
+export interface ParsedSyncplayRuntimeRoomMetadata {
+    readonly runtimeIdentity: SyncplayRuntimeIdentity;
+    readonly sessionConfigBytes: Uint8Array;
+    readonly sessionConfigDigest: string;
+}
+/** A game's runtime config, as its simulation module exports it. */
+export interface SyncplayRuntimeConfigInput {
+    readonly runtimeIdentity: SyncplayRuntimeIdentity;
+    readonly sessionConfigBytes: Uint8Array;
+    readonly sessionConfigDigest: string;
+}
+export declare function parseSyncplayRuntimeRoomMetadata(value: unknown): ParsedSyncplayRuntimeRoomMetadata;
+/**
+ * Mint the wire-shaped runtime pin a build stamps into its rooms config.
+ *
+ * Validates through `parseSyncplayRuntimeRoomMetadata`, so a pin that mints is
+ * a pin that publishes and loads. Throws rather than returning a bad pin: the
+ * room server treats the pin as authoritative over player-supplied ticket
+ * metadata, so a wrong pin is worse than no pin.
+ */
+export declare function createSyncplayRuntimePin(input: SyncplayRuntimeConfigInput): SyncplayRuntimeRoomMetadata;

package/dist/runtime-room-metadata.js

@@ -0,0 +1,84 @@
+/**
+ * The runtime a deterministic room simulates: engine identity plus the
+ * canonical session config (the game's rules) it was created with.
+ *
+ * This is the ONE implementation. The build mints a pin with
+ * `createSyncplayRuntimePin`, the publish path validates it, and the room
+ * server validates it again on room create — all through
+ * `parseSyncplayRuntimeRoomMetadata` below. A second copy of these rules is how
+ * a pin could pass one gate and fail another.
+ */
+import { kinetixSessionConfigDigest, MAX_KINETIX_SESSION_CONFIG_BYTES, } from '@series-inc/rundot-syncplay/core/runtime';
+export const MAX_SYNCPLAY_SESSION_CONFIG_BYTES = MAX_KINETIX_SESSION_CONFIG_BYTES;
+export function parseSyncplayRuntimeRoomMetadata(value) {
+    if (!isRecord(value) || !hasExactKeys(value, ['runtimeIdentity', 'sessionConfigBytes', 'sessionConfigDigest'])) {
+        throw new Error('syncplay runtime metadata is missing or malformed');
+    }
+    const identity = value.runtimeIdentity;
+    if (!isRecord(identity)
+        || !hasExactKeys(identity, ['abiVersion', 'tickRate', 'inputSchemaId', 'stateSchemaId', 'deterministicVersion', 'engineIdentityHash'])
+        || identity.abiVersion !== 1
+        || ![10, 20, 30, 60].includes(identity.tickRate)
+        || !isNonEmptyString(identity.inputSchemaId)
+        || !isNonEmptyString(identity.stateSchemaId)
+        || !isNonEmptyString(identity.deterministicVersion)
+        || !isNonEmptyString(identity.engineIdentityHash)) {
+        throw new Error('syncplay runtime identity is malformed');
+    }
+    if (typeof value.sessionConfigBytes !== 'string' || !isCanonicalBase64(value.sessionConfigBytes)) {
+        throw new Error('syncplay session config bytes are not canonical base64');
+    }
+    const bytes = Uint8Array.from(Buffer.from(value.sessionConfigBytes, 'base64'));
+    if (bytes.byteLength < 1 || bytes.byteLength > MAX_SYNCPLAY_SESSION_CONFIG_BYTES) {
+        throw new Error('syncplay session config bytes are empty or oversized');
+    }
+    if (typeof value.sessionConfigDigest !== 'string'
+        || value.sessionConfigDigest !== kinetixSessionConfigDigest(bytes)) {
+        throw new Error('syncplay session config digest mismatch');
+    }
+    return {
+        runtimeIdentity: identity,
+        sessionConfigBytes: bytes,
+        sessionConfigDigest: value.sessionConfigDigest,
+    };
+}
+/**
+ * Mint the wire-shaped runtime pin a build stamps into its rooms config.
+ *
+ * Validates through `parseSyncplayRuntimeRoomMetadata`, so a pin that mints is
+ * a pin that publishes and loads. Throws rather than returning a bad pin: the
+ * room server treats the pin as authoritative over player-supplied ticket
+ * metadata, so a wrong pin is worse than no pin.
+ */
+export function createSyncplayRuntimePin(input) {
+    // Check the caller's own keys before re-shaping: building a fresh object
+    // would silently drop a stray top-level key instead of rejecting it.
+    if (!isRecord(input)
+        || !hasExactKeys(input, ['runtimeIdentity', 'sessionConfigBytes', 'sessionConfigDigest'])) {
+        throw new Error('syncplay runtime config must carry exactly runtimeIdentity, sessionConfigBytes, sessionConfigDigest');
+    }
+    if (!(input.sessionConfigBytes instanceof Uint8Array)) {
+        throw new Error('syncplay runtime config sessionConfigBytes must be a Uint8Array');
+    }
+    const pin = {
+        runtimeIdentity: input.runtimeIdentity,
+        sessionConfigBytes: Buffer.from(input.sessionConfigBytes).toString('base64'),
+        sessionConfigDigest: input.sessionConfigDigest,
+    };
+    parseSyncplayRuntimeRoomMetadata(pin);
+    return pin;
+}
+function hasExactKeys(value, expected) {
+    return Object.keys(value).sort().join('\0') === [...expected].sort().join('\0');
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isCanonicalBase64(value) {
+    if (value.length === 0 || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/u.test(value))
+        return false;
+    return Buffer.from(value, 'base64').toString('base64') === value;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/session-snapshot.d.ts

@@ -51,6 +51,30 @@ export declare function encodeDeterministicStateSnapshot(snapshot: Deterministic
 export declare function decodeDeterministicStateSnapshot(text: string): DeterministicStateSnapshotDecodeResult;
 export declare function bytesToBase64(bytes: Uint8Array): string;
 export declare function base64ToBytes(text: string): Uint8Array;
+/**
+ * Fixed bytes the wire framing adds around a chunk: 225 B for the
+ * `snapshot-chunk` envelope plus 76 B for the SDK transport's outer
+ * {type,msgType,data} wrapper. Held at 512 B for headroom on transferId and
+ * checksum length changes.
+ */
+export declare const SNAPSHOT_CHUNK_ENVELOPE_OVERHEAD_BYTES = 512;
+/**
+ * Worst-case multiplicative growth of a chunk string on its way to the wire.
+ * `snapshotBytes` is JSON (`encodeDeterministicStateSnapshot` -> canonicalStringify),
+ * NOT base64, so it is quote-dense — and it is JSON-escaped TWICE: into the
+ * `snapshot-chunk` envelope, then again when the SDK transport stringifies the
+ * outer message (run-room-transport `sendRaw` -> RundotServerRoom
+ * {type,msgType,data} -> ServerWebSocket `JSON.stringify`). A `"` becomes `\"`
+ * becomes `\\\"`. Measured at exactly 4.001x for all-quote and all-backslash
+ * payloads; a realistic base64-dominated snapshot lands at ~1.001x.
+ *
+ * The room server's boot guard requires
+ * WS_MAX_MESSAGE_SIZE >= DEFAULT_SNAPSHOT_CHUNK_SIZE * this + the fixed overhead.
+ * A cap below that makes `ws` raise "Max payload size exceeded" and close the
+ * socket 1006, failing every snapshot transfer for that room — the 2026-08-25
+ * lattice incident. See .plans/syncplay-snapshot-cap-and-observability.md.
+ */
+export declare const MAX_JSON_ESCAPE_EXPANSION = 4;
 export declare const DEFAULT_SNAPSHOT_CHUNK_SIZE = 262144;
 export declare const DEFAULT_MAX_SNAPSHOT_BYTES = 4194304;
 export interface CreateSnapshotTransferOptions {

package/dist/session-snapshot.js

@@ -155,6 +155,30 @@ export function base64ToBytes(text) {
     return bytes;
 }
 // ── transfer builder (raw bytes → frozen wire transfer shape) ──
+/**
+ * Fixed bytes the wire framing adds around a chunk: 225 B for the
+ * `snapshot-chunk` envelope plus 76 B for the SDK transport's outer
+ * {type,msgType,data} wrapper. Held at 512 B for headroom on transferId and
+ * checksum length changes.
+ */
+export const SNAPSHOT_CHUNK_ENVELOPE_OVERHEAD_BYTES = 512;
+/**
+ * Worst-case multiplicative growth of a chunk string on its way to the wire.
+ * `snapshotBytes` is JSON (`encodeDeterministicStateSnapshot` -> canonicalStringify),
+ * NOT base64, so it is quote-dense — and it is JSON-escaped TWICE: into the
+ * `snapshot-chunk` envelope, then again when the SDK transport stringifies the
+ * outer message (run-room-transport `sendRaw` -> RundotServerRoom
+ * {type,msgType,data} -> ServerWebSocket `JSON.stringify`). A `"` becomes `\"`
+ * becomes `\\\"`. Measured at exactly 4.001x for all-quote and all-backslash
+ * payloads; a realistic base64-dominated snapshot lands at ~1.001x.
+ *
+ * The room server's boot guard requires
+ * WS_MAX_MESSAGE_SIZE >= DEFAULT_SNAPSHOT_CHUNK_SIZE * this + the fixed overhead.
+ * A cap below that makes `ws` raise "Max payload size exceeded" and close the
+ * socket 1006, failing every snapshot transfer for that room — the 2026-08-25
+ * lattice incident. See .plans/syncplay-snapshot-cap-and-observability.md.
+ */
+export const MAX_JSON_ESCAPE_EXPANSION = 4;
 export const DEFAULT_SNAPSHOT_CHUNK_SIZE = 262_144;
 export const DEFAULT_MAX_SNAPSHOT_BYTES = 4_194_304;
 export function createSnapshotTransferFromBytes(snapshotBytes, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/rundot-syncplay",
-  "version": "5.26.0-beta.9",
+  "version": "5.26.0",
   "description": "Kinetix orchestration, rollback, replay, late-join, and deterministic networking for RUN.game",
   "repository": {
     "type": "git",
@@ -160,7 +160,8 @@
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "test": "npm run test:core && npm run test:unit-control && npm run test:entity-registry",
     "test:module-promotion": "node --expose-gc --import tsx --test tests/module-promotion.test.ts tests/module-docs.test.ts tests/module-bundle-budget.test.ts scripts/prove-module-promotion.test.mjs",
-    "test:core": "node --expose-gc --import tsx --test --test-concurrency=1 tests/canonical.test.ts tests/canonical-portability.test.ts tests/runtime-session.test.ts tests/kinetix-runtime-session.test.ts tests/runtime-support.test.ts tests/runtime-guards.test.ts tests/r3f-render-adapter.test.ts tests/snapshot-cost.test.ts tests/sdkSession.test.ts tests/input-authority.test.ts tests/session-wire.test.ts tests/session-snapshot.test.ts tests/authority-room.test.ts tests/networked-client-snapshot.test.ts tests/runner.test.ts tests/testing.test.ts tests/browser-session.test.ts tests/secret-config.test.ts tests/secret-protocol.test.ts tests/secret-authority.test.ts tests/secret-client.test.ts tests/late-join-checksum.test.ts tests/late-join-input-backfill.test.ts tests/replay-scoring.test.ts tests/bot-backfill.test.ts tests/latency-simulation.test.ts tests/production-input-budget.test.ts tests/time-sync.test.ts tests/match-log.test.ts tests/spectator.test.ts tests/synctest.test.ts tests/instant-replay.test.ts tests/session-promotion.test.ts tests/physics3d-broadphase-stats.test.ts tests/entrypoints.test.ts tests/export-surface.test.ts tests/module-seam.test.ts tests/module-contract-portability.test.ts tests/module-identity.test.ts tests/module-corpus.test.ts tests/component-model.test.ts tests/component-model-rollback.test.ts tests/component-model-integration.test.ts tests/actors-ai.test.ts tests/character-3d.test.ts tests/character-3d-certification.test.ts tests/combat-modules.test.ts tests/combat-modules-integration.test.ts tests/firearm.test.ts tests/gameplay-effects.test.ts tests/spatial-interaction.test.ts tests/stats-abilities.test.ts tests/inventory-equipment.test.ts tests/inventory-equipment-certification.test.ts tests/platformer-2d.test.ts tests/platformer-2d-certification.test.ts tests/module-promotion.test.ts tests/module-docs.test.ts tests/module-bundle-budget.test.ts tests/published-side-effects.test.ts tests/host-timing.test.ts tests/test-manifest.test.ts tests/coarse-region.test.ts tests/input-codec.test.ts tests/command-ingress.test.ts tests/session-reconfigure.test.ts tests/prediction-mode.test.ts tests/ephemeral-channel.test.ts tests/runner-surface.test.ts tests/runner-harness.test.ts tests/effects-adapter-bounds.test.ts tests/simulated-match-secrets.test.ts tests/run-glue-surface.test.mjs core/tests/core-boundary.test.mjs tests/math-core-parity.test.ts tests/math-profile.test.ts tests/movement3d-kcc-unit-contract.test.ts tests/movement3d-static-ground.test.ts",
+    "test:core": "node --expose-gc --import tsx --test --test-concurrency=1 tests/canonical.test.ts tests/canonical-portability.test.ts tests/runtime-session.test.ts tests/kinetix-runtime-session.test.ts tests/runtime-support.test.ts tests/runtime-guards.test.ts tests/r3f-render-adapter.test.ts tests/snapshot-cost.test.ts tests/sdkSession.test.ts tests/input-authority.test.ts tests/session-wire.test.ts tests/runtime-room-metadata.test.ts tests/session-snapshot.test.ts tests/authority-room.test.ts tests/networked-client-snapshot.test.ts tests/runner.test.ts tests/testing.test.ts tests/browser-session.test.ts tests/secret-config.test.ts tests/secret-protocol.test.ts tests/secret-authority.test.ts tests/secret-client.test.ts tests/late-join-checksum.test.ts tests/late-join-input-backfill.test.ts tests/replay-scoring.test.ts tests/bot-backfill.test.ts tests/latency-simulation.test.ts tests/production-input-budget.test.ts tests/time-sync.test.ts tests/match-log.test.ts tests/spectator.test.ts tests/synctest.test.ts tests/instant-replay.test.ts tests/session-promotion.test.ts tests/physics3d-broadphase-stats.test.ts tests/entrypoints.test.ts tests/export-surface.test.ts tests/module-seam.test.ts tests/module-contract-portability.test.ts tests/module-identity.test.ts tests/module-corpus.test.ts tests/component-model.test.ts tests/component-model-rollback.test.ts tests/component-model-integration.test.ts tests/actors-ai.test.ts tests/character-3d.test.ts tests/character-3d-certification.test.ts tests/combat-modules.test.ts tests/combat-modules-integration.test.ts tests/firearm.test.ts tests/gameplay-effects.test.ts tests/spatial-interaction.test.ts tests/stats-abilities.test.ts tests/inventory-equipment.test.ts tests/inventory-equipment-certification.test.ts tests/platformer-2d.test.ts tests/platformer-2d-certification.test.ts tests/module-promotion.test.ts tests/module-docs.test.ts tests/module-bundle-budget.test.ts tests/published-side-effects.test.ts tests/host-timing.test.ts tests/test-manifest.test.ts tests/coarse-region.test.ts tests/input-codec.test.ts tests/command-ingress.test.ts tests/session-reconfigure.test.ts tests/prediction-mode.test.ts tests/ephemeral-channel.test.ts tests/runner-surface.test.ts tests/runner-harness.test.ts tests/effects-adapter-bounds.test.ts tests/simulated-match-secrets.test.ts tests/run-glue-surface.test.mjs core/tests/core-boundary.test.mjs tests/math-core-parity.test.ts tests/math-profile.test.ts tests/movement3d-kcc-unit-contract.test.ts tests/movement3d-static-ground.test.ts",
+    "test:sdk-contract": "node --import tsx --test tests/sdk-runtime-contract.test.ts",
     "test:soak": "tsx --test tests/runtime-soak.test.ts",
     "test:extended": "tsx --test tests/kcc-vehicle-characterization.test.ts tests/animation.test.ts tests/asset-cooking.test.ts tests/backend-proof-checksum-vectors.test.ts tests/bot-documents.test.ts tests/bot-primitives.test.ts tests/collider-cooking.test.ts tests/collision.test.ts tests/command-timeline.test.ts tests/config-bundle.test.ts tests/cosmetic-physics3d.test.ts tests/deterministic-primitives.test.ts tests/ecs-lite.test.ts tests/effects-adapter.test.ts tests/engine-runtime.test.ts tests/errors.test.ts tests/events.test.ts tests/input-button.test.ts tests/load-128-players.test.ts tests/math.test.ts tests/movement.test.ts tests/movement3d.test.ts tests/multiclient-authority.test.ts tests/navigation.test.ts tests/noise.test.ts tests/physics-cert.test.ts tests/physics2d.test.ts tests/physics3d-ccd.test.ts tests/physics3d-coverage.test.ts tests/physics3d-destruction-cert.test.ts tests/physics3d-geometry-limits.test.ts tests/physics3d-heightfield.test.ts tests/physics3d-hull.test.ts tests/physics3d-joints.test.ts tests/physics3d-kinematic-mesh.test.ts tests/physics3d-mass.test.ts tests/physics3d-materials.test.ts tests/physics3d-mesh-onesided.test.ts tests/physics3d-query-index.test.ts tests/physics3d-recipes.test.ts tests/physics3d-rotation-convention.test.ts tests/physics3d-shared.test.ts tests/physics3d-sleeping-manifold-reuse.test.ts tests/physics3d-solver.test.ts tests/physics3d-static-memoization.test.ts tests/physics3d-static-overlap-memo.test.ts tests/physics3d-cylinder-hull.test.ts tests/physics3d-stacking.test.ts tests/physics3d-toi.test.ts tests/physics3d-vehicle.test.ts tests/physics3d-voxel.test.ts tests/physics3d-world-edit.test.ts tests/physics3d.test.ts tests/physics-vector-generator.test.ts tests/random.test.ts tests/rollback-history.test.ts tests/schema-artifacts.test.ts tests/schema-codegen.test.ts tests/schema-dsl-binary.test.ts tests/schema.test.ts tests/signals.test.ts tests/sparse-set.test.ts tests/static-checker.test.ts tests/system-lifecycle.test.ts tests/wire-canonical-sentinels.test.ts tests/ws-frame.test.ts",
     "test:ci": "npm run build && npm run test",