@series-inc/rundot-syncplay 5.25.0-beta.0 → 5.25.0-beta.10

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 |
@@ -20,10 +25,12 @@ There is one session factory:
 
 ```ts
 import { createSyncplaySession } from '@series-inc/rundot-syncplay/browser';
-import { createFixed1000Runtime } from '@series-inc/rundot-kinetix/runtime';
+import { createInstalledPlatformer2dRuntime } from '@series-inc/rundot-kinetix/runtime';
 
-const runtime = createFixed1000Runtime({
-  product,
+const runtime = createInstalledPlatformer2dRuntime({
+  pack,
+  levelBytes,
+  identity,
   sessionConfigBytes,
 });
 
@@ -32,12 +39,15 @@ const session = createSyncplaySession(runtime, {
   defaultInput: { throttle: 0, steer: 0, brake: false },
   snapshotBufferSize: 256,
   checksumIntervalFrames: 30,
+  requires: { projection: true },
 });
 ```
 
 The runtime must implement `@series-inc/rundot-kinetix/runtime`. Syncplay never
 accepts an initial state, reducer, or creator-authored step callback. There is no
-compatibility mode for the removed reducer API.
+compatibility mode for the removed reducer API. A non-platformer game supplies
+the same ABI through `createInstalledRuntimeAdapter` and binds its source with
+`deriveCustomRuntimeIdentity` plus `kinetixRuntimeModuleManifest`.
 
 ## Runtime and snapshot contract
 
@@ -52,6 +62,50 @@ session-config bytes, asks the game for a matching runtime through its runtime
 factory, and rejects a locally loaded pack mismatch before frame 0. Replays use
 the same identity/config/factory path.
 
+### Capability requirements
+
+Session policies and runner configs accept
+`requires?: { commands?: boolean; projection?: boolean }`. Requirements are
+checked when each offline or networked session is constructed, before any frame
+advances:
+
+| Requirement | Failure |
+|---|---|
+| `projection: true` without `runtime.project` | `SYNCPLAY_PROJECTION_UNSUPPORTED` |
+| `commands: true` with no capabilities declaration | `SYNCPLAY_RUNTIME_CAPABILITY_UNKNOWN` |
+| `commands: true` with `capabilities.commands !== true` | `SYNCPLAY_RUNTIME_COMMANDS_UNSUPPORTED` |
+
+The runner forwards one `requires` policy through both `startOffline()` and
+`startNetworked()`, including reconfigured network sessions. Unknown capability
+metadata never silently passes negotiation.
+
+## Presentation frames
+
+`session.getState()` returns a detached deep copy of the current frame, which
+costs O(state) per read and is unaffordable for a large mutable world (a
+destructible voxel city, a big streaming map).
+
+`session.getPresentationFrame()` is the no-clone path. It calls the runtime's
+optional `project(checkpoint, previous)` and returns the result untouched:
+
+- **Requires** a runtime built with a `projectState` hook. A runtime without
+  `project` throws `SYNCPLAY_PROJECTION_UNSUPPORTED` — there is no silent
+  fallback to `inspect`.
+- **The result is immutable.** Callers must not mutate it. It may share structure
+  with authoritative state and with previously returned projections, which is
+  exactly what lets a renderer diff persistent roots and skip shared subtrees.
+- **`previous` is the last frame this session projected**, enabling delta
+  projections. It is absent — meaning the runtime should produce a full frame —
+  on the first call, after `restoreToFrame` or `restoreSnapshot`, and whenever
+  the previously projected frame is no longer retained (pruned or rolled past).
+- **Reading the same frame twice is free and idempotent.** Repeat calls return
+  the identical projection rather than re-projecting the frame against itself
+  (which would report an empty delta). Authoritative state cannot change without
+  the frame advancing, so multiple render passes per frame are safe.
+
+Projections are presentation-only: they never re-enter simulation and are not
+part of deterministic identity.
+
 ## Public projections and secrets
 
 Every peer applies the same confirmed inputs and authority commands. Optional
@@ -83,3 +137,165 @@ The core suite covers checkpoint ownership/release, frame-zero rollback, v2
 snapshot hydration, replay verification, authority persistence, latency/loss
 convergence, late join, spectators, bots, secrets, and a real Kinetix world
 driven through `createSyncplaySession`.
+
+## Unified session runner
+
+`createSyncplayRunner` owns the offline / co-op / networked lifecycle behind one
+runtime factory and one presentation contract, so a game does not re-implement
+create/join resolution, the local/network tick branch, bot filling, projection
+extraction, and stale-connection invalidation:
+
+```ts
+const runner = createSyncplayRunner({
+  runtimeFactory,
+  prepareNetworkRuntime: (descriptor, signal) => prepareLevelFromUgc(descriptor, signal),
+  defaultInput,
+  encodeInput,
+  decodeInput,
+  presentation: {
+    project: (frame) => frame,
+    interpolate: interpolateRenderState,
+    events: (frame) => frame.events,
+  },
+})
+runner.startOffline({ identity, sessionConfigBytes, playerCount: 2, botInputForTick })
+await runner.startNetworked(() => createSyncplayRoom(api.realtime, roomOptions))
+runner.applyInput(readInput())
+runner.update(deltaMs)
+render(runner.getRenderState(), runner.renderAlpha)
+```
+
+**Status** is exactly `offline | connecting | syncing | live | stopped | error`:
+
+- `connecting` covers the room-open promise.
+- `syncing` covers session-descriptor/asset preparation, reconnect, and catch-up.
+- `live` requires `client.caughtUp` plus at least one applied authority frame.
+- `offline` owns the local fixed-step accumulator and bot filling.
+- `error` carries connection, preparation, and offline-construction failures on
+  the runner snapshot (and the throw is rethrown to the caller).
+- `stop` aborts preparation, closes the transport, and disposes the active
+  client/session — idempotently.
+
+Presentation stays **predicted** for render motion, while side-effect events are
+delivered only from authority-confirmed frames received after the first live
+boundary. Initial and reconnect catch-up history is silent; a post-live
+authority-leading frame still emits its event exactly once. Interpolation is
+presentation-only and never feeds simulation. Starting a new mode always tears
+down the old one, and a stale async connection/preparation closes without
+replacing the current session.
+
+**Incremental adoption (mature games).** A game with its own stateful renderer,
+input model, and connection UI can swap only its lifecycle orchestration onto the
+runner without rewriting those layers:
+
+- Keep your own presentation singleton — use an identity `project: (frame) => frame`
+  and feed your renderer from the `subscribe` snapshot (`renderState`, `renderAlpha`)
+  instead of `getRenderState()`.
+- Supply `localInputForTick: (slot, frame) => Input` when your local input is a
+  per-tick pulse/edge that must be consumed and cleared each frame; the runner then
+  reads it (offline local slot and networked prediction) instead of the persistent
+  `applyInput(...)` value.
+- Drive a room badge from the snapshot's `ready`, `appliedThrough`, `predictedThrough`,
+  `localSlot`, and `status` — no reach into the underlying client (e.g. `appliedThrough < 0`
+  means "waiting for peers"; `predictedThrough - appliedThrough` is the catch-up depth).
+- Tune the networked client through the runner: `pacing` (`targetLeadTicks`,
+  `maxStepsPerPump`, drift correction) and `inputDelay` (`minTicks`/`maxTicks`,
+  RTT-adaptive) are forwarded verbatim, and live `netStats` (RTT, timescale, input
+  delay) is surfaced on the snapshot + runner (`null` offline) for a netcode HUD.
+
+Direct `NetworkedSyncplayClient` users get the same projection surface:
+`getPresentationFrame()`, `renderAlpha`, `currentFrame`, `caughtUp`, and a
+bounded confirmed-frame queue via the optional `confirmedPresentationBufferSize`
+(absent = no queue, preserving existing cost) drained with
+`drainConfirmedPresentationFrames()`. Call `beginPresentationCatchUp()` from your
+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 `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
+verified separately and never rides a snapshot. `maxPredictionTicks` is a
+rollback/latency budget, not a player-count limit. 128 slots is the tested
+protocol/load ceiling, not a 60 Hz performance guarantee for an arbitrary game.
+
+## Supported correctness kit
+
+`@series-inc/rundot-syncplay/testing` exposes exactly nine supported
+entry points — no browser or runtime APIs leak through it:
+
+```ts
+import {
+  assertDeterministic,
+  assertLateJoinHydration,
+  assertPresentationParity,
+  assertReplayVerifies,
+  assertRunnerLifecycle,
+  assertTwoClientConvergence,
+  createSimulatedSyncplayMatch,
+  createSyncplayRunnerHarness,
+  runSyncplaySynctest,
+} from '@series-inc/rundot-syncplay/testing'
+```
+
+`assertDeterministic` and `assertReplayVerifies` run the straight-run /
+restore-resim / hydration / replay cert; `assertTwoClientConvergence` and
+`assertLateJoinHydration` run the **real** authority room and networked client
+over a deterministic simulated network (`createSimulatedSyncplayMatch`,
+`runSyncplaySynctest`). `createSyncplayRunnerHarness`, `assertRunnerLifecycle`,
+and `assertPresentationParity` cover the runner seam — a real runner driven on
+a fully controlled clock against the simulated match. Failures name the phase,
+frame, and disagreeing checksums.

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;