@series-inc/rundot-syncplay 5.25.0-beta.6 → 5.25.0-beta.7

package/README.md

@@ -5,6 +5,11 @@ deterministic state, RNG streams, stepping, opaque checkpoints, serialization,
 hydration, and checksums. Syncplay owns inputs, prediction, confirmation,
 rollback policy, replay logs, late join, secrets, and transport.
 
+> **Upgrading an existing game?** See
+> [MIGRATING-SESSION-PRIMITIVES.md](./MIGRATING-SESSION-PRIMITIVES.md). Two
+> changes are not additive: the runner now rejects an unsafe input codec at
+> construction, and the effects adapter now dedupes on your event `dedupeKey`.
+
 ## Ownership boundary
 
 | Concern | Owner |
@@ -184,8 +189,60 @@ bounded confirmed-frame queue via the optional `confirmedPresentationBufferSize`
 transport's reconnect signal so replayed history never fills the queue.
 `prepareNetworkedSyncplayTransport(transport, prepare, { signal })` buffers the
 ordered `session-start`/history traffic (same 8,192-message ceiling as the SDK
-transport), exposes a frozen descriptor with `levelEntryId + digest + length`,
-awaits your async preparation, then replays every buffered message once.
+transport), exposes a frozen `NetworkedSyncplaySessionDescriptor`, awaits your
+async preparation, then replays every buffered message once.
+
+The descriptor is exactly `{ slot, playerCount, seed, tickRateHz,
+hardToleranceTicks, role, runtimeIdentity, sessionConfigBytes,
+sessionConfigDigest }`. It does **not** carry `levelEntryId`, a level digest, or a
+level length — those are game-specific fields inside `sessionConfigBytes`, and you
+decode them with your own session-config schema:
+
+```ts
+import { decodeKinetixSessionConfig } from '@series-inc/rundot-kinetix/runtime';
+import { kinetixPlatformer2dSessionConfigSchema } from '@series-inc/rundot-kinetix/runtime';
+
+const prepareNetworkRuntime = async (descriptor, signal) => {
+  const session = decodeKinetixSessionConfig(
+    kinetixPlatformer2dSessionConfigSchema,
+    descriptor.sessionConfigBytes,
+  );
+  // session.levelEntryId / session.levelDigest / session.levelByteLength
+  const levelBytes = await preparePlatformerLevel(api.ugc, {
+    levelEntryId: session.levelEntryId,
+    levelDigest: session.levelDigest,
+    levelByteLength: session.levelByteLength,
+    encodeLevel: (level) => encodeKinetixPlatformer2dLevel(level, { maxBytes: 102_400 }),
+  });
+  registerPreparedLevel(descriptor.sessionConfigDigest, levelBytes);
+};
+```
+
+## Safe input codecs
+
+`defineSyncplayInputCodec(schema)` derives `{ encodeInput, decodeInput,
+neutralInput }` from an exact field declaration (`boolean`, `int` with
+`min`/`max`, `enum` of numbers). Decoding a non-conforming payload throws
+`SYNCPLAY_INPUT_DECODE_INVALID`, and the canonical `null` substitute maps to
+`neutralInput` — i.e. correct `decodeInputSafe` semantics by construction, rather
+than by remembering to write them. Neutral is `false` for booleans and `0` for
+numeric fields when their range admits it; otherwise the field must declare
+`neutral` or construction throws `SYNCPLAY_INPUT_SCHEMA_INVALID`.
+
+For an existing hand-written codec, `validateSyncplayInputCodec({ encodeInput,
+decodeInput, samples })` probes round-trip stability, `null → neutral`, and a
+battery of hostile payloads, failing with `SYNCPLAY_INPUT_CODEC_UNSAFE`.
+
+## Version-safe content references
+
+`publishPlatformerLevel(api, level, options)` always calls `ugc.create` — never
+`ugc.update` on a referenced entry, which would make every live room pinned to it
+permanently unjoinable. `preparePlatformerLevel(api, declaration)` resolves a pin
+and raises the typed `SYNCPLAY_LEVEL_CONTENT_CHANGED` (naming the entry id and the
+edit-vs-pin cause) rather than an opaque `KINETIX_AUX_ASSET_MISMATCH` deep inside
+runtime construction. `declaration.encodeLevel` is an **injected callback**, not a
+static Kinetix import, because Syncplay must compile against both the published
+Kinetix pin and an overlaid local build.
 
 **Capacity and late-join budgets.** Snapshot transfer defaults are **256 KiB**
 chunks and a **4 MiB** total ceiling; the immutable level payload is fetched and

package/dist/authority-room.d.ts

@@ -106,6 +106,23 @@ export interface DeterministicAuthorityRoomConfig {
     readonly secrets?: SyncplaySecretSystemsConfig;
     readonly secretCrypto?: SyncplaySecretAuthorityCrypto;
     readonly secretMsgType?: string;
+    /** Per-slot ceiling on accepted `command-request` messages in a one-second window. Default 60. */
+    readonly commandsPerSecond?: number;
+    /**
+     * Who may drive {@link DeterministicAuthorityRoom.reconfigureSession} over the
+     * wire. Default 'none' — a `reconfigure-request` is dropped and counted, and
+     * only the host may reconfigure in-process.
+     */
+    readonly reconfigurePolicy?: 'creator' | 'any' | 'none';
+    /** The creator's seat, required to enforce `reconfigurePolicy: 'creator'`. */
+    readonly creatorSlot?: number;
+}
+export interface DeterministicAuthorityRoomReconfiguration {
+    readonly sessionConfigBytes: Uint8Array;
+    readonly sessionConfigDigest: string;
+    readonly seed?: number;
+    /** When supplied, must equal the live identity; a mismatch throws. */
+    readonly runtimeIdentity?: KinetixRuntimeIdentity;
 }
 export interface DeterministicAuthorityRoomRestoreState {
     readonly now: number;
@@ -119,6 +136,8 @@ export interface DeterministicAuthorityRoomRestoreState {
     readonly sessionConfigBytes: Uint8Array;
     readonly sessionConfigDigest: string;
     readonly secretState?: SyncplaySecretAuthoritySnapshot;
+    /** Session generation at persist time; a restored room re-greets with it. Default 0. */
+    readonly generation?: number;
 }
 export interface AuthorityRoomCatchUpEvent {
     readonly playerId: string;
@@ -161,6 +180,12 @@ export interface AuthorityRoomNetcodeStats {
     /** Ticks in which each slot's input had to be substituted (cumulative). */
     readonly substitutedTicksBySlot: Readonly<Record<number, number>>;
     readonly clientStats: Readonly<Record<number, AuthorityRoomClientNetStats>>;
+    /** Command requests dropped for seat, size, rate, sequence, or stale generation. */
+    readonly rejectedCommands: number;
+    /** Reconfigure requests dropped for policy or size. */
+    readonly rejectedReconfigures: number;
+    /** Ephemeral relays dropped for seat, size, or rate. */
+    readonly rejectedEphemeral: number;
 }
 export interface AuthorityRoomJoinResult {
     readonly accepted: boolean;
@@ -178,8 +203,11 @@ export interface AuthorityRoomSnapshot {
     /** Lowest confirmed tick still retained (-1 when nothing is confirmed). */
     readonly earliestRetainedTick: number;
     readonly runtimeIdentity: KinetixRuntimeIdentity;
+    /** The CURRENT session config (post-reconfigure), not the creation-time one. */
     readonly sessionConfigBytes: Uint8Array;
     readonly sessionConfigDigest: string;
+    /** Session generation: 0 until the first reconfigure. */
+    readonly generation: number;
     /**
      * Metadata of the latest VALIDATED state snapshot. The raw bytes are
      * deliberately excluded — hosts persist this record (mp-room-server hard-caps
@@ -213,6 +241,16 @@ export interface DeterministicAuthorityRoom {
     onPlayerReconnected(playerId: string): void;
     /** Advance the authority by one server tick and broadcast newly-confirmed frames. */
     onTick(): void;
+    /**
+     * Swap the session config in a live room: bumps the generation, resets the
+     * authority's own session state, and re-greets every seated player and
+     * spectator with a fresh `session-start`. Nobody disconnects — clients treat
+     * a differing generation as a full session swap. Throws
+     * SYNCPLAY_RECONFIGURE_IDENTITY_MISMATCH when the supplied runtime identity
+     * differs from the live one, and SYNCPLAY_RECONFIGURE_CONFIG_INVALID on bad
+     * or oversized bytes.
+     */
+    reconfigureSession(next: DeterministicAuthorityRoomReconfiguration): void;
     snapshot(): AuthorityRoomSnapshot;
     /** Raw bytes of the latest validated state snapshot (see AuthorityRoomSnapshot.latestSnapshot). */
     latestSnapshotBytes(): string | undefined;

package/dist/authority-room.js

@@ -1,10 +1,10 @@
-import { defaultChecksum } from './canonical.js';
+import { canonicalStringify, defaultChecksum, encodeUtf8 } from './canonical.js';
 import { assertKinetixRuntimeIdentity, kinetixSessionConfigDigest, } from '@series-inc/rundot-kinetix/runtime';
 import { invariant } from './errors.js';
 import { createInputAuthority } from './input-authority.js';
 import { createDeterministicLocalAuthoritySnapshotChunkEnvelope, createDeterministicLocalAuthoritySnapshotCompleteEnvelope, createDeterministicLocalAuthoritySnapshotOfferEnvelope, createDeterministicLocalAuthoritySnapshotRequestEnvelope, decodeDeterministicLocalAuthorityWireEnvelope, } from './local-authority-wire.js';
 import { DEFAULT_SNAPSHOT_CHUNK_SIZE, createSnapshotTransferCollector, createSnapshotTransferFromBytes, decodeDeterministicStateSnapshot, deterministicRoomDescriptorHash, } from './session-snapshot.js';
-import { MAX_KINETIX_SESSION_CONFIG_BYTES, decodeDeterministicSessionMessage, encodeDeterministicSessionMessage, } from './session-wire.js';
+import { MAX_KINETIX_SESSION_CONFIG_BYTES, MAX_SYNCPLAY_COMMAND_PAYLOAD_BYTES, MAX_SYNCPLAY_EPHEMERAL_PAYLOAD_BYTES, decodeDeterministicSessionMessage, encodeDeterministicSessionMessage, } from './session-wire.js';
 import { createSyncplaySecretAuthority, } from './secret-authority.js';
 const DEFAULT_SESSION_MSG_TYPE = 'rdm';
 const DEFAULT_SECRET_MSG_TYPE = 'rdm-secret';
@@ -16,6 +16,10 @@ const HISTORY_CHUNK_FRAMES = 500;
 const DEFAULT_SNAPSHOT_CADENCE_TICKS = 3600;
 /** Ten seconds at 60 Hz — see DeterministicAuthorityRoomConfig.transferTimeoutTicks. */
 const DEFAULT_TRANSFER_TIMEOUT_TICKS = 600;
+/** See DeterministicAuthorityRoomConfig.commandsPerSecond. */
+const DEFAULT_COMMANDS_PER_SECOND = 60;
+/** Per-slot ephemeral relay ceiling per one-second window (matches the client's outbound coalescing). */
+const EPHEMERAL_RELAYS_PER_SECOND = 20;
 export function createDeterministicAuthorityRoom(transport, config) {
     assertKinetixRuntimeIdentity(config.runtimeIdentity);
     invariant(config.runtimeIdentity.tickRate === config.tickRateHz, 'runtime identity tick rate does not match the authority clock', 'authority-room.runtime-tick-rate');
@@ -30,10 +34,20 @@ export function createDeterministicAuthorityRoom(transport, config) {
     }
     const sessionMsgType = config.sessionMsgType ?? DEFAULT_SESSION_MSG_TYPE;
     const historyRetentionTicks = config.historyRetentionTicks ?? DEFAULT_HISTORY_RETENTION_TICKS;
+    const commandsPerSecond = config.commandsPerSecond ?? DEFAULT_COMMANDS_PER_SECOND;
+    invariant(Number.isInteger(commandsPerSecond) && commandsPerSecond >= 0, 'commandsPerSecond must be a non-negative integer', 'authority-room.commands-per-second');
+    const reconfigurePolicy = config.reconfigurePolicy ?? 'none';
+    // Mutable session identity: reconfigureSession swaps these, and every greet,
+    // snapshot validation, and persisted record must read the CURRENT values.
+    let sessionConfigBytes = config.sessionConfigBytes.slice();
+    let sessionConfigDigest = config.sessionConfigDigest;
+    let seed = config.seed;
+    let generation = config.restoreFrom?.generation ?? 0;
+    invariant(Number.isInteger(generation) && generation >= 0, 'restored generation must be a non-negative integer', 'authority-room.restore-generation');
     if (config.maxSnapshotBytes !== undefined && (!Number.isInteger(config.maxSnapshotBytes) || config.maxSnapshotBytes < 1)) {
         throw new Error(`createDeterministicAuthorityRoom: maxSnapshotBytes must be a positive integer, received ${config.maxSnapshotBytes}`);
     }
-    const authority = createInputAuthority({
+    const createSessionAuthority = (restoreFrom) => createInputAuthority({
         playerCount: config.playerCount,
         hardToleranceTicks: config.hardToleranceTicks,
         neutralInput: config.neutralInput,
@@ -43,10 +57,11 @@ export function createDeterministicAuthorityRoom(transport, config) {
         // (historyRetentionTicks — explicit caller choice wins; the generous floor
         // lives in DEFAULT_HISTORY_RETENTION_TICKS, not here, so tests can shrink it).
         retainedConfirmedFrames: Math.max(historyRetentionTicks, config.redundancyWindowTicks * 4),
-        ...(config.restoreFrom === undefined
-            ? {}
-            : { restoreFrom: { confirmedThrough: config.restoreFrom.confirmedThrough, frames: config.restoreFrom.tail } }),
+        ...(restoreFrom === undefined ? {} : { restoreFrom }),
     });
+    let authority = createSessionAuthority(config.restoreFrom === undefined
+        ? undefined
+        : { confirmedThrough: config.restoreFrom.confirmedThrough, frames: config.restoreFrom.tail });
     const slotByPlayer = new Map();
     // G11 spectators: read-only connections with no slot. Their input /
     // checksum-report / net-stats envelopes are already dropped by the
@@ -81,12 +96,13 @@ export function createDeterministicAuthorityRoom(transport, config) {
     // snapshot and runs at most one donor transfer at a time.
     const snapshotCadenceTicks = config.snapshotCadenceTicks ?? DEFAULT_SNAPSHOT_CADENCE_TICKS;
     const transferTimeoutTicks = config.transferTimeoutTicks ?? DEFAULT_TRANSFER_TIMEOUT_TICKS;
-    const roomDescriptorHash = deterministicRoomDescriptorHash({
-        seed: config.seed,
+    const describeRoom = () => deterministicRoomDescriptorHash({
+        seed,
         playerCount: config.playerCount,
         tickRateHz: config.tickRateHz,
         hardToleranceTicks: config.hardToleranceTicks,
     });
+    let roomDescriptorHash = describeRoom();
     let storedSnapshot;
     let pendingTransfer;
     let nextCadenceTarget = snapshotCadenceTicks;
@@ -98,6 +114,14 @@ export function createDeterministicAuthorityRoom(transport, config) {
     // once per newly-confirmed tick) and the latest client-reported stats.
     const substitutedTicksBySlot = new Map();
     const clientNetStatsBySlot = new Map();
+    // Command ingress bookkeeping: per-slot sliding acceptance window (in authority
+    // ticks) and the last accepted sequence, both reset by a reconfigure.
+    let commandTicksBySlot = new Map();
+    let lastCommandSequenceBySlot = new Map();
+    const ephemeralTicksBySlot = new Map();
+    let rejectedCommands = 0;
+    let rejectedReconfigures = 0;
+    let rejectedEphemeral = 0;
     let substitutionCountedThrough = -1;
     // Highest tick ever included in a confirmed-input broadcast — the anchor
     // that guarantees frontier jumps larger than the redundancy window can
@@ -126,7 +150,7 @@ export function createDeterministicAuthorityRoom(transport, config) {
             const decoded = decodeDeterministicStateSnapshot(restore.snapshotBytes);
             invariant(decoded.ok, 'restored snapshotBytes do not decode', 'authority-room.restore-snapshot');
             invariant(equalRuntimeIdentity(decoded.snapshot.runtimeIdentity, config.runtimeIdentity)
-                && decoded.snapshot.sessionConfigDigest === config.sessionConfigDigest, 'restored snapshot runtime identity or config digest does not match the room', 'authority-room.restore-snapshot-runtime-config');
+                && decoded.snapshot.sessionConfigDigest === sessionConfigDigest, 'restored snapshot runtime identity or config digest does not match the room', 'authority-room.restore-snapshot-runtime-config');
             // With preserveFullHistory the persisted tail reaches back to tick 0
             // (below the snapshot); a tail starting ABOVE the snapshot tick would
             // leave an unreplayable gap and must still fail loud.
@@ -159,13 +183,16 @@ export function createDeterministicAuthorityRoom(transport, config) {
             kind: 'session-start',
             slot,
             playerCount: config.playerCount,
-            seed: config.seed,
+            seed,
             tickRateHz: config.tickRateHz,
             hardToleranceTicks: config.hardToleranceTicks,
             role,
             runtimeIdentity: config.runtimeIdentity,
-            sessionConfigBytes: config.sessionConfigBytes.slice(),
-            sessionConfigDigest: config.sessionConfigDigest,
+            sessionConfigBytes: sessionConfigBytes.slice(),
+            sessionConfigDigest,
+            // Omitted at generation 0 so a room that never reconfigures encodes
+            // byte-identically to what pre-generation peers expect.
+            ...(generation === 0 ? {} : { generation }),
         }));
     }
     /**
@@ -379,12 +406,31 @@ export function createDeterministicAuthorityRoom(transport, config) {
             }));
             return;
         }
-        if (message.kind !== 'input' && message.kind !== 'checksum-report' && message.kind !== 'net-stats') {
+        if (message.kind !== 'input' && message.kind !== 'checksum-report' && message.kind !== 'net-stats'
+            && message.kind !== 'command-request' && message.kind !== 'ephemeral' && message.kind !== 'reconfigure-request') {
             return;
         }
         const slot = slotByPlayer.get(playerId);
         // Server owns the slot mapping — a client cannot act for a slot it was not assigned.
         if (slot === undefined || message.slot !== slot) {
+            if (message.kind === 'command-request')
+                rejectedCommands += 1;
+            else if (message.kind === 'ephemeral')
+                rejectedEphemeral += 1;
+            else if (message.kind === 'reconfigure-request')
+                rejectedReconfigures += 1;
+            return;
+        }
+        if (message.kind === 'command-request') {
+            acceptCommandRequest(slot, message.generation, message.sequence, message.command);
+            return;
+        }
+        if (message.kind === 'ephemeral') {
+            relayEphemeral(playerId, slot, message.payload);
+            return;
+        }
+        if (message.kind === 'reconfigure-request') {
+            acceptReconfigureRequest(slot, message.sessionConfigBytes, message.sessionConfigDigest, message.seed);
             return;
         }
         if (message.kind === 'input') {
@@ -404,6 +450,118 @@ export function createDeterministicAuthorityRoom(transport, config) {
             });
         }
     }
+    /**
+     * Sliding one-second acceptance window, measured in authority ticks so the
+     * limit is clock-free (the room owns no wall clock). Returns false when the
+     * slot is over budget.
+     */
+    function admitInWindow(windows, slot, perSecond) {
+        const floor = now - config.tickRateHz + 1;
+        const retained = (windows.get(slot) ?? []).filter((tick) => tick >= floor);
+        if (retained.length >= perSecond) {
+            windows.set(slot, retained);
+            return false;
+        }
+        retained.push(now);
+        windows.set(slot, retained);
+        return true;
+    }
+    function acceptCommandRequest(slot, requestGeneration, sequence, command) {
+        // A stale generation means the request was authored against a session that
+        // no longer exists — applying it would mutate the wrong level.
+        if (requestGeneration !== generation) {
+            rejectedCommands += 1;
+            return;
+        }
+        const lastSequence = lastCommandSequenceBySlot.get(slot);
+        if (lastSequence !== undefined && sequence <= lastSequence) {
+            rejectedCommands += 1;
+            return;
+        }
+        if (canonicalStringifyByteLength(command.payload) > MAX_SYNCPLAY_COMMAND_PAYLOAD_BYTES) {
+            rejectedCommands += 1;
+            return;
+        }
+        if (!admitInWindow(commandTicksBySlot, slot, commandsPerSecond)) {
+            rejectedCommands += 1;
+            return;
+        }
+        lastCommandSequenceBySlot.set(slot, sequence);
+        // The same tick-assignment path secret commands use, so canonicalization,
+        // confirmed-frame distribution, replay, and snapshots need no change.
+        const tick = Math.max(now, authority.confirmedThrough) + 1;
+        authority.queueCommand(tick, {
+            kind: `game.${command.kind}`,
+            slot,
+            payload: command.payload,
+        });
+    }
+    function relayEphemeral(senderId, slot, payload) {
+        if (canonicalStringifyByteLength(payload) > MAX_SYNCPLAY_EPHEMERAL_PAYLOAD_BYTES) {
+            rejectedEphemeral += 1;
+            return;
+        }
+        if (!admitInWindow(ephemeralTicksBySlot, slot, EPHEMERAL_RELAYS_PER_SECOND)) {
+            rejectedEphemeral += 1;
+            return;
+        }
+        const encoded = encodeDeterministicSessionMessage({ kind: 'ephemeral', slot, payload });
+        for (const playerId of [...slotByPlayer.keys(), ...spectators]) {
+            if (playerId === senderId)
+                continue;
+            transport.sendTo(playerId, sessionMsgType, encoded);
+        }
+    }
+    function acceptReconfigureRequest(slot, nextBytes, nextDigest, nextSeed) {
+        const authorized = reconfigurePolicy === 'any'
+            || (reconfigurePolicy === 'creator' && config.creatorSlot !== undefined && slot === config.creatorSlot);
+        if (!authorized || nextBytes.byteLength > MAX_KINETIX_SESSION_CONFIG_BYTES) {
+            rejectedReconfigures += 1;
+            return;
+        }
+        reconfigureSession({
+            sessionConfigBytes: nextBytes,
+            sessionConfigDigest: nextDigest,
+            ...(nextSeed === undefined ? {} : { seed: nextSeed }),
+        });
+    }
+    function reconfigureSession(next) {
+        if (next.runtimeIdentity !== undefined && !equalRuntimeIdentity(next.runtimeIdentity, config.runtimeIdentity)) {
+            throw new Error('SYNCPLAY_RECONFIGURE_IDENTITY_MISMATCH');
+        }
+        if (!(next.sessionConfigBytes instanceof Uint8Array)
+            || next.sessionConfigBytes.byteLength === 0
+            || next.sessionConfigBytes.byteLength > MAX_KINETIX_SESSION_CONFIG_BYTES
+            || kinetixSessionConfigDigest(next.sessionConfigBytes) !== next.sessionConfigDigest) {
+            throw new Error('SYNCPLAY_RECONFIGURE_CONFIG_INVALID');
+        }
+        generation += 1;
+        sessionConfigBytes = next.sessionConfigBytes.slice();
+        sessionConfigDigest = next.sessionConfigDigest;
+        if (next.seed !== undefined)
+            seed = next.seed;
+        roomDescriptorHash = describeRoom();
+        // The tick space restarts at 0: every client full-resets on the differing
+        // generation, so retained history, snapshots, and reports all describe a
+        // session that no longer exists.
+        authority = createSessionAuthority();
+        storedSnapshot = undefined;
+        pendingTransfer = undefined;
+        checksumReports.clear();
+        reportsDirty = false;
+        substitutedTicksBySlot.clear();
+        substitutionCountedThrough = -1;
+        commandTicksBySlot = new Map();
+        lastCommandSequenceBySlot = new Map();
+        nextCadenceTarget = snapshotCadenceTicks;
+        broadcastThrough = -1;
+        restoredRoom = false;
+        now = -1;
+        for (const [playerId, slot] of slotByPlayer)
+            sendSessionStart(playerId, slot);
+        for (const playerId of spectators)
+            sendSessionStart(playerId, -1, 'spectator');
+    }
     function recordChecksumReport(slot, tick, checksum) {
         let reports = checksumReports.get(tick);
         if (reports === undefined) {
@@ -507,7 +665,7 @@ export function createDeterministicAuthorityRoom(transport, config) {
             return;
         }
         if (!equalRuntimeIdentity(snapshot.runtimeIdentity, config.runtimeIdentity)
-            || snapshot.sessionConfigDigest !== config.sessionConfigDigest) {
+            || snapshot.sessionConfigDigest !== sessionConfigDigest) {
             failPendingTransfer('snapshot-runtime-config-mismatch');
             return;
         }
@@ -704,8 +862,9 @@ export function createDeterministicAuthorityRoom(transport, config) {
                 everSlots: Object.fromEntries(everSlotByPlayer),
                 earliestRetainedTick: authority.earliestRetainedTick,
                 runtimeIdentity: config.runtimeIdentity,
-                sessionConfigBytes: config.sessionConfigBytes.slice(),
-                sessionConfigDigest: config.sessionConfigDigest,
+                sessionConfigBytes: sessionConfigBytes.slice(),
+                sessionConfigDigest,
+                generation,
                 ...(storedSnapshot === undefined
                     ? {}
                     : {
@@ -741,15 +900,19 @@ export function createDeterministicAuthorityRoom(transport, config) {
                 confirmedThrough: authority.confirmedThrough,
                 substitutedTicksBySlot: Object.fromEntries(substitutedTicksBySlot),
                 clientStats: Object.fromEntries(clientNetStatsBySlot),
+                rejectedCommands,
+                rejectedReconfigures,
+                rejectedEphemeral,
             };
         },
+        reconfigureSession,
         matchLog() {
             if (authority.confirmedThrough < 0 || !historyReachesTickZero()) {
                 return undefined;
             }
             return {
                 v: 1,
-                seed: config.seed,
+                seed,
                 tickRateHz: config.tickRateHz,
                 playerCount: config.playerCount,
                 hardToleranceTicks: config.hardToleranceTicks,
@@ -763,6 +926,9 @@ export function createDeterministicAuthorityRoom(transport, config) {
         },
     };
 }
+function canonicalStringifyByteLength(value) {
+    return encodeUtf8(canonicalStringify(value)).byteLength;
+}
 function requireSecretAuthorityId(authorityId) {
     invariant(typeof authorityId === 'string' && authorityId.length > 0, 'secret authorityId is required', 'authority-room.secret-authority-id');
     return authorityId;

package/dist/browser.d.ts

@@ -11,6 +11,8 @@ export { createDeterministicEventEffectsAdapter } from './effects-adapter.js';
 export { assertDeterministicFrameHeapStaleHandleError, assertDeterministicFrameSystemsStateless, compileDeterministicDslRuntimeDescriptor, createDeterministicBitset, createDeterministicFrameRuntime, createDeterministicFrameRuntimeAccessors, createDeterministicSlotMap, createDeterministicSparseSetFrameRuntime, generateDeterministicFrameRuntimeSource, isDeterministicFrameHeapStaleHandleError, runDeterministicFrameRuntimeMutationCorpus, validateDeterministicFrameSystemsStateless } from './engine-runtime.js';
 export { createDeterministicEventTimeline, filterDeterministicEventsForPlayer } from './events.js';
 export { createInputAuthority } from './input-authority.js';
+export { defineSyncplayInputCodec, validateSyncplayInputCodec } from './input-codec.js';
+export { preparePlatformerLevel, publishPlatformerLevel, SYNCPLAY_PLATFORMER_LEVEL_CONTENT_TYPE, SYNCPLAY_PLATFORMER_LEVEL_DATA_KEY } from './platformer-content.js';
 export { createInstantReplayRunner, runInstantReplay } from './instant-replay.js';
 export { buildDeterministicLagCompensatedHitboxProxies3D, createDeterministicLagCompensation3DHistory, rewindDeterministicLagCompensatedTargets3D, validateDeterministicAuthoritativeLagCompensatedShot3D, validateDeterministicLagCompensatedShot3D } from './lag-compensation3d.js';
 export { createDeterministicLocalAuthoritySnapshotChunkEnvelope, createDeterministicLocalAuthoritySnapshotCompleteEnvelope, createDeterministicLocalAuthoritySnapshotOfferEnvelope, createDeterministicLocalAuthoritySnapshotRequestEnvelope, decodeDeterministicLocalAuthorityWireEnvelope, deterministicLocalAuthorityWireProtocol, encodeDeterministicLocalAuthorityWireEnvelope } from './local-authority-wire.js';
@@ -51,6 +53,8 @@ export type { DeterministicEffectDispatch, DeterministicEffectTarget, Determinis
 export type { DeterministicCommandAccessor, DeterministicComponentAccessor, DeterministicComponentData, DeterministicComponentDescriptor, DeterministicComponentFieldDescriptor, DeterministicComponentFieldKind, DeterministicComponentFixedArrayFieldKind, DeterministicComponentFrameHeapFieldKind, DeterministicComponentScalarFieldKind, DeterministicDslRuntimeCompileOptions, DeterministicEntityRef, DeterministicEventAccessor, DeterministicFrameHeapCollectionKind, DeterministicFrameHeapCollectionSnapshot, DeterministicFrameHeapHandle, DeterministicFrameHeapSnapshot, DeterministicFrameQueryFilter, DeterministicFrameRuntime, DeterministicFrameRuntimeAccessors, DeterministicFrameRuntimeDescriptor, DeterministicFrameRuntimeOptions, DeterministicFrameSnapshot, DeterministicQueryRow, DeterministicRuntimeMessage, DeterministicRuntimePayloadDescriptor, DeterministicRuntimeSignalHandler, DeterministicSignalAccessor, DeterministicSingletonAccessor, DeterministicStatelessSystemDiagnostic, DeterministicStatelessSystemDiagnosticReason, DeterministicStatelessSystemValidationResult, DeterministicSystem, DeterministicSystemContext, DeterministicSystemDescriptor } from './engine-runtime.js';
 export type { DeterministicEventDeliveryScope, DeterministicEventEmitOptions, DeterministicEventPredictionState, DeterministicEventRecord, DeterministicEventTimeline } from './events.js';
 export type { ConfirmedInputFrame, EncodedInput, InputAuthority, InputAuthorityConfig, InputAuthorityRestoreState, InputAuthorityStats, InputRejectionReason, InputSubmissionResult } from './input-authority.js';
+export type { SyncplayBooleanInputField, SyncplayEnumInputField, SyncplayInputCodec, SyncplayInputCodecProbe, SyncplayInputField, SyncplayInputSchema, SyncplayIntInputField } from './input-codec.js';
+export type { PlatformerLevelDeclaration, PlatformerLevelUgcApi, PlatformerLevelUgcCreateParams, PlatformerLevelUgcEntry, PublishPlatformerLevelOptions } from './platformer-content.js';
 export type { InstantReplayInputFrame, InstantReplayResult, InstantReplayRunner, InstantReplayRunnerOptions, InstantReplayRunOptions, RunInstantReplayOptions } from './instant-replay.js';
 export type { DeterministicAuthoritativeLagCompensation3DShotContext, DeterministicLagCompensatedPellet3DResult, DeterministicLagCompensatedShot3D, DeterministicLagCompensatedShot3DResult, DeterministicLagCompensatedTarget3D, DeterministicLagCompensation3DHistory, DeterministicLagCompensation3DHistoryOptions, DeterministicLagCompensation3DHistorySnapshot, DeterministicLagCompensation3DRewindSnapshot } from './lag-compensation3d.js';
 export type { DeterministicLocalAuthoritySnapshotIdentity, DeterministicLocalAuthoritySnapshotTransfer, DeterministicLocalAuthorityWireEnvelope, DeterministicLocalAuthorityWireKind } from './local-authority-wire.js';
@@ -59,8 +63,8 @@ export type { DeterministicFpsAimState, DeterministicFpsInput, DeterministicKccB
 export type { DeterministicKccBody3D, DeterministicKccCarrierPose3D, DeterministicKccCarryResult3D, DeterministicKccCarryState3D, DeterministicKccCollisionCandidate3D, DeterministicKccCollisionFilter3D, DeterministicKccExternalImpulse3D, DeterministicKccGeometry3D, DeterministicKccInput3D, DeterministicKccPhysicsImpulse3D, DeterministicKccProcessor3D, DeterministicKccStepResult3D, DeterministicKccWorld3D, DeterministicMovingPlatform3D, DeterministicSlope3D, DeterministicStep3D } from './movement3d.js';
 export type { CookedDeterministicNavigationGraph, DeterministicFlowField, DeterministicNavEdge, DeterministicNavigationAgent, DeterministicNavigationGraphSource, DeterministicNavigationStepOptions, DeterministicNavigationStepResult, DeterministicNavNode, DeterministicNavRegion, DeterministicPathQuery, DeterministicPathResult, DeterministicTilemapSource } from './navigation.js';
 export type { CookedDeterministicNavmesh, DeterministicNavmeshAgent, DeterministicNavmeshAgentStepResult, DeterministicNavmeshImportSource, DeterministicNavmeshLink, DeterministicNavmeshMovingAvoidanceObstacle, DeterministicNavmeshOffMeshTraversalState, DeterministicNavmeshOffMeshTraversalStep, DeterministicNavmeshPath, DeterministicNavmeshPoint, DeterministicNavmeshPolygon, DeterministicNavmeshSource } from './navmesh.js';
-export type { ConfirmedSyncplayPresentationFrame, KinetixRuntimeFactory, NetworkedClientTransport, NetworkedSyncplayClient, NetworkedSyncplayClientInputDelayOptions, NetworkedSyncplayClientNetStats, NetworkedSyncplayClientOptions, NetworkedSyncplayClientPacingOptions, NetworkedSyncplayPreparationOptions, NetworkedSyncplaySessionDescriptor, NetworkedSyncplaySlotPresence, PreparedNetworkedSyncplayTransport } from './networked-client.js';
-export type { SyncplayRunner, SyncplayRunnerConfig, SyncplayRunnerConnectionEvent, SyncplayRunnerOfflineOptions, SyncplayRunnerPresentation, SyncplayRunnerSnapshot, SyncplayRunnerStatus, SyncplayRunnerTransport } from './runner.js';
+export type { ConfirmedSyncplayPresentationFrame, KinetixRuntimeFactory, NetworkedClientTransport, NetworkedSyncplayClient, NetworkedSyncplayClientInputDelayOptions, NetworkedSyncplayClientNetStats, NetworkedSyncplayClientOptions, NetworkedSyncplayClientPacingOptions, NetworkedSyncplayPreparationOptions, NetworkedSyncplaySessionDescriptor, NetworkedSyncplaySlotPresence, PreparedNetworkedSyncplayTransport, SyncplayPredictionMode } from './networked-client.js';
+export type { SyncplayRunner, SyncplayRunnerConfig, SyncplayRunnerConnectionEvent, SyncplayRunnerOccupancy, SyncplayRunnerOfflineOptions, SyncplayRunnerPresentation, SyncplayRunnerSnapshot, SyncplayRunnerStatus, SyncplayRunnerTransport } from './runner.js';
 export type { DeterministicBodyKind, DeterministicContactEvent2D, DeterministicContactEventType, DeterministicPhysicsAabbQuery2D, DeterministicPhysicsActivePair2D, DeterministicPhysicsBody2D, DeterministicPhysicsCircleCastQuery2D, DeterministicPhysicsConstraint2D, DeterministicPhysicsHit2D, DeterministicPhysicsQueryOptions2D, DeterministicPhysicsRaycastQuery2D, DeterministicPhysicsShape2D, DeterministicPhysicsShapeOverlapQuery2D, DeterministicPhysicsStepOptions2D, DeterministicPhysicsStepResult2D, DeterministicPhysicsWorld2D } from './physics2d.js';
 export type { DeterministicContactCacheEntry3D, DeterministicJointCacheEntry3D, DeterministicPhysicsActivePair3D, DeterministicPhysicsAxisLock3D, DeterministicPhysicsBody3D, DeterministicPhysicsCallbackMask3D, DeterministicPhysicsCompoundChild3D, DeterministicPhysicsCompoundChildShape3D, DeterministicPhysicsConstraint3D, DeterministicPhysicsContactDetail3D, DeterministicPhysicsContactEvent3D, DeterministicPhysicsDetailedHit3D, DeterministicPhysicsHit3D, DeterministicPhysicsHullShape3D, DeterministicPhysicsImpulseApplication3D, DeterministicPhysicsOverlapQuery3D, DeterministicPhysicsPrimitiveShape3D, DeterministicPhysicsQuaternion3D, DeterministicPhysicsQueryOptions3D, DeterministicPhysicsRaycastQuery3D, DeterministicPhysicsScheduledQuery3D, DeterministicPhysicsShape3D, DeterministicPhysicsShapeCastQuery3D, DeterministicPhysicsStepResult3D, DeterministicPhysicsVec3, DeterministicPhysicsWorld3D, DeterministicPhysicsWorldEdit3D } from './physics3d.js';
 export type { DeterministicVoxelChunk3D, DeterministicVoxelCompoundShape3D } from './physics3d-voxel.js';
@@ -71,7 +75,7 @@ export type { SchemaBinaryProof, SchemaBinarySourceOptions, SchemaTypesOptions }
 export type { DeterministicBinarySerializer, DeterministicDslDeclaration, DeterministicDslDeclarationKind, DeterministicDslDictionaryEntry, DeterministicDslDictionaryFieldKind, DeterministicDslField, DeterministicDslFieldKind, DeterministicDslFixedArrayFieldKind, DeterministicDslListFieldKind, DeterministicDslScalarFieldKind, DeterministicDslScalarValue, DeterministicDslSchema, DeterministicDslSetFieldKind, DeterministicDslValue } from './schema-dsl-binary.js';
 export type { SyncplaySession, SyncplaySessionPolicy } from './sdk-session.js';
 export type { CollectedSnapshotTransfer, CreateSnapshotTransferOptions, DeterministicStateSnapshot, DeterministicStateSnapshotDecodeRejection, DeterministicStateSnapshotDecodeResult, SnapshotTransferCollector, SnapshotTransferCollectorOptions, SnapshotTransferCompleteResult, SnapshotTransferRejection, SnapshotTransferStepResult } from './session-snapshot.js';
-export type { DeterministicSessionDecodeRejection, DeterministicSessionDecodeResult, DeterministicSessionMessage, DeterministicSessionMessageKind, DeterministicSessionRole } from './session-wire.js';
+export type { DeterministicCommandRequestMessage, DeterministicEphemeralMessage, DeterministicReconfigureRequestMessage, DeterministicSessionDecodeRejection, DeterministicSessionDecodeResult, DeterministicSessionMessage, DeterministicSessionMessageKind, DeterministicSessionRole } from './session-wire.js';
 export type { DeterministicSignal, DeterministicSignalBus, DeterministicSignalBusSnapshot, DeterministicSignalSubscription } from './signals.js';
 export type { DeterministicSparseSet, DeterministicSparseSetSnapshot } from './sparse-set.js';
 export type { DeterministicLifecycleCounterSummary, DeterministicLifecycleRunner, DeterministicLifecycleSignal, DeterministicLifecycleSnapshot, DeterministicLifecycleSystemContext, DeterministicLifecycleSystemDescriptor, DeterministicLifecycleSystemHooks } from './system-lifecycle.js';

package/dist/browser.js

@@ -12,6 +12,8 @@ export { createDeterministicEventEffectsAdapter } from './effects-adapter.js';
 export { assertDeterministicFrameHeapStaleHandleError, assertDeterministicFrameSystemsStateless, compileDeterministicDslRuntimeDescriptor, createDeterministicBitset, createDeterministicFrameRuntime, createDeterministicFrameRuntimeAccessors, createDeterministicSlotMap, createDeterministicSparseSetFrameRuntime, generateDeterministicFrameRuntimeSource, isDeterministicFrameHeapStaleHandleError, runDeterministicFrameRuntimeMutationCorpus, validateDeterministicFrameSystemsStateless } from './engine-runtime.js';
 export { createDeterministicEventTimeline, filterDeterministicEventsForPlayer } from './events.js';
 export { createInputAuthority } from './input-authority.js';
+export { defineSyncplayInputCodec, validateSyncplayInputCodec } from './input-codec.js';
+export { preparePlatformerLevel, publishPlatformerLevel, SYNCPLAY_PLATFORMER_LEVEL_CONTENT_TYPE, SYNCPLAY_PLATFORMER_LEVEL_DATA_KEY } from './platformer-content.js';
 export { createInstantReplayRunner, runInstantReplay } from './instant-replay.js';
 export { buildDeterministicLagCompensatedHitboxProxies3D, createDeterministicLagCompensation3DHistory, rewindDeterministicLagCompensatedTargets3D, validateDeterministicAuthoritativeLagCompensatedShot3D, validateDeterministicLagCompensatedShot3D } from './lag-compensation3d.js';
 export { createDeterministicLocalAuthoritySnapshotChunkEnvelope, createDeterministicLocalAuthoritySnapshotCompleteEnvelope, createDeterministicLocalAuthoritySnapshotOfferEnvelope, createDeterministicLocalAuthoritySnapshotRequestEnvelope, decodeDeterministicLocalAuthorityWireEnvelope, deterministicLocalAuthorityWireProtocol, encodeDeterministicLocalAuthorityWireEnvelope } from './local-authority-wire.js';

package/dist/dev-authority-room.js

@@ -39,6 +39,8 @@ export class DevSyncplayAuthorityRoom {
             ? undefined
             : validateSyncplaySecretSystemsConfig(deterministic.secrets, playerCount);
         const secretCrypto = secretConfig === undefined ? undefined : createEphemeralSecretCrypto();
+        const reconfigurePolicy = deterministic?.reconfigurePolicy;
+        const commandsPerSecond = deterministic?.commandsPerSecond;
         // The server owns the seed: derive it deterministically from the room id so
         // every client of this room receives the same seed (same scheme as prod).
         const seed = deriveSeed(ctx.roomId);
@@ -55,6 +57,16 @@ export class DevSyncplayAuthorityRoom {
             sessionConfigBytes: runtime.sessionConfigBytes,
             sessionConfigDigest: runtime.sessionConfigDigest,
             redundancyWindowTicks: readPositiveInt(config.redundancyWindowTicks, DEFAULT_REDUNDANCY_WINDOW_TICKS),
+            // Collaborative-editing knobs, read from the same `deterministic` block
+            // the production room server reads. Without these a `reconfigurePolicy`
+            // a creator declared in their realtime config is silently ignored under
+            // `npm run dev`, and every publish is dropped by the default 'none'.
+            ...(reconfigurePolicy === undefined ? {} : { reconfigurePolicy }),
+            ...(commandsPerSecond === undefined ? {} : { commandsPerSecond }),
+            // Slot 0 is the room's first seat — the creator in the create-and-share
+            // flow. The dev sidecar has no platform identity to consult, so this
+            // matches the production wrapper's choice.
+            creatorSlot: 0,
             // Game-agnostic no-op input: the authority substitutes canonical null for
             // a slot with no prior input; the client maps null to the game's default.
             neutralInput: null,

package/dist/effects-adapter.d.ts

@@ -14,8 +14,14 @@ export interface DeterministicEventEffectsAdapter<Payload, Effect> {
     subscribe(listener: (dispatch: DeterministicEffectDispatch<Payload, Effect>) => void): () => void;
     reset(): void;
 }
+export declare const DEFAULT_EFFECT_RETENTION_FRAMES = 1024;
 export interface DeterministicEventEffectsAdapterConfig<Payload, Effect> {
     readonly target: DeterministicEffectTarget;
     readonly mapEvent: (record: DeterministicEventRecord<Payload>) => Effect | undefined;
+    /**
+     * How far behind the newest dispatched frame a record is still remembered for
+     * dedupe, in frames. Defaults to {@link DEFAULT_EFFECT_RETENTION_FRAMES}.
+     */
+    readonly retentionFrames?: number;
 }
 export declare function createDeterministicEventEffectsAdapter<Payload, Effect>(config: DeterministicEventEffectsAdapterConfig<Payload, Effect>): DeterministicEventEffectsAdapter<Payload, Effect>;

package/dist/effects-adapter.js

@@ -1,21 +1,48 @@
 import { cloneCanonical } from './canonical.js';
 import { stableSortedKeys } from './collections.js';
 import { SyncplayError } from './errors.js';
+export const DEFAULT_EFFECT_RETENTION_FRAMES = 1024;
 export function createDeterministicEventEffectsAdapter(config) {
     validateTarget(config.target);
-    const dispatched = [];
-    const seen = new Set();
+    const retentionFrames = config.retentionFrames ?? DEFAULT_EFFECT_RETENTION_FRAMES;
+    if (!Number.isSafeInteger(retentionFrames) || retentionFrames < 1) {
+        throw new SyncplayError(`Effect retention must be a positive integer, got ${String(retentionFrames)}`, {
+            code: 'effects.retention',
+        });
+    }
+    let dispatched = [];
+    const seen = new Map();
     const listeners = new Set();
+    let newestFrame = 0;
+    // Both `seen` and `dispatched` used to grow until teardown, so a long match
+    // leaked one entry per event forever. Records older than the retention window
+    // can no longer be re-delivered by the confirmed-frame ring, so dropping them
+    // cannot resurrect a duplicate.
+    const prune = () => {
+        const horizon = newestFrame - retentionFrames;
+        if (horizon <= 0)
+            return;
+        for (const [key, frame] of seen) {
+            if (frame < horizon)
+                seen.delete(key);
+        }
+        if (dispatched.length > 0 && dispatched[0].record.frame < horizon) {
+            dispatched = dispatched.filter((entry) => entry.record.frame >= horizon);
+        }
+    };
     return {
         dispatch(records) {
             const nextDispatches = [];
             for (const record of records) {
-                const dedupeKey = `${record.sequence}:${record.predictionState}`;
+                // A game-supplied dedupeKey is authoritative: sequence alone collides
+                // across frames once a runtime restarts its per-frame numbering.
+                const dedupeKey = record.dedupeKey ?? `${record.frame}:${record.sequence}:${record.predictionState}`;
                 if (seen.has(dedupeKey)) {
                     continue;
                 }
                 const effect = config.mapEvent(cloneEventRecord(record));
-                seen.add(dedupeKey);
+                seen.set(dedupeKey, record.frame);
+                newestFrame = Math.max(newestFrame, record.frame);
                 if (effect === undefined) {
                     continue;
                 }
@@ -30,8 +57,10 @@ export function createDeterministicEventEffectsAdapter(config) {
                     listener(dispatch);
                 }
             }
+            prune();
             return nextDispatches;
         },
+        /** Bounded: only dispatches within the retention window are retained. */
         getDispatched() {
             return dispatched.map((dispatch) => freezeEffectDispatch({
                 target: dispatch.target,
@@ -46,8 +75,9 @@ export function createDeterministicEventEffectsAdapter(config) {
             };
         },
         reset() {
-            dispatched.length = 0;
+            dispatched = [];
             seen.clear();
+            newestFrame = 0;
         },
     };
 }