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

package/dist/random.d.ts

@@ -1,3 +1,4 @@
+import type { DeterministicMath } from './math.js';
 export interface DeterministicRandomSnapshot {
     readonly state: number;
 }
@@ -8,6 +9,12 @@ export declare class DeterministicRandom {
     nextInt(minInclusive: number, maxInclusive: number): number;
     nextFixed(scale?: number): number;
     fork(label: string | number): DeterministicRandom;
+    nextBool(): boolean;
+    nextRangeFixed(minFixed: number, maxFixed: number): number;
+    nextAngleTurns(fixedScale: number): number;
+    pickOne<T>(items: readonly T[]): T;
+    weighted<T>(items: readonly T[], weights: readonly number[]): T;
+    gaussian(math: DeterministicMath): number;
     snapshot(): DeterministicRandomSnapshot;
     restore(snapshot: DeterministicRandomSnapshot): void;
 }

package/dist/random.js

@@ -33,6 +33,55 @@ export class DeterministicRandom {
         child.restore({ state: (this.state ^ labelHash) >>> 0 });
         return child;
     }
+    nextBool() {
+        return (this.nextUint32() & 1) === 1;
+    }
+    nextRangeFixed(minFixed, maxFixed) {
+        if (maxFixed <= minFixed) {
+            throw new Error('DeterministicRandom.nextRangeFixed: max <= min');
+        }
+        const span = maxFixed - minFixed;
+        return minFixed + Math.trunc((this.nextUint32() / 4294967296) * span);
+    }
+    nextAngleTurns(fixedScale) {
+        return Math.trunc((this.nextUint32() / 4294967296) * fixedScale);
+    }
+    pickOne(items) {
+        if (items.length === 0) {
+            throw new Error('DeterministicRandom.pickOne: empty');
+        }
+        return items[this.nextInt(0, items.length - 1)];
+    }
+    weighted(items, weights) {
+        if (items.length !== weights.length || items.length === 0) {
+            throw new Error('DeterministicRandom.weighted: length mismatch');
+        }
+        let total = 0;
+        for (const w of weights) {
+            if (w < 0) {
+                throw new Error('DeterministicRandom.weighted: negative weight');
+            }
+            total += w;
+        }
+        if (total <= 0) {
+            throw new Error('DeterministicRandom.weighted: non-positive total');
+        }
+        let r = this.nextInt(0, total - 1);
+        for (let i = 0; i < items.length; i += 1) {
+            r -= weights[i];
+            if (r < 0) {
+                return items[i];
+            }
+        }
+        return items[items.length - 1];
+    }
+    gaussian(math) {
+        // Box-Muller: sqrt(-2 ln u1) * cos(2π u2), u1 in (0,1]. Fixed-point.
+        const u1 = math.max(this.nextFixed(math.fixedScale), 1);
+        const u2 = this.nextFixed(math.fixedScale);
+        const r = math.sqrt(math.mul(math.toFixed(2), math.abs(math.log(u1))));
+        return math.mul(r, math.cosTurns(u2)); // u2 already in [0,scale) turns
+    }
     snapshot() {
         return { state: this.state };
     }

package/dist/replay-bundle.d.ts

@@ -1,6 +1,6 @@
 import { type CanonicalValue } from './canonical.js';
 import { type DeterministicFrameRuntime, type DeterministicFrameRuntimeDescriptor, type DeterministicSystem } from './engine-runtime.js';
-import type { RecordedChecksum, RecordedCommandFrame, RecordedDebugEvent, RecordedInputFrame } from './types.js';
+import type { RecordedChecksum, RecordedCommandFrame, RecordedDebugEvent, RecordedInputFrame, ReplayFile } from './types.js';
 export interface DeterministicReplayBundle {
     readonly schemaVersion: 1;
     readonly runtimeVersion: string;
@@ -141,6 +141,45 @@ export declare function verifyDeterministicFrameRuntimeReplayBundle(bundle: Dete
 export declare function verifyDeterministicSelfContainedFrameRuntimeReplayBundle(bundle: DeterministicReplayBundle, options?: {
     readonly sparse?: boolean;
 }): DeterministicFrameRuntimeReplayBundleVerification;
+/**
+ * The trusted rules artifact the score re-run needs, extracted from a certify
+ * replay bundle at deploy and stored server-side keyed by `deterministicVersion`.
+ * It carries the built-in runtime `descriptor` + `systemId` + `beforeFrameId`
+ * (never client-supplied) plus the identity fields the re-run gates on. The
+ * client's `ReplayFile.initialState` and authored-state checksums are NOT part of
+ * this manifest and are never trusted.
+ */
+export interface DeterministicReplayVerificationManifest {
+    readonly deterministicVersion: string;
+    readonly inputSchemaId: string;
+    readonly stateSchemaId: string;
+    readonly descriptor: DeterministicFrameRuntimeDescriptor;
+    readonly systemId: DeterministicReplayRuntimeSystemId;
+    readonly beforeFrameId: DeterministicReplayRuntimeBeforeFrameId;
+    readonly seed: number;
+    readonly sparse?: boolean;
+}
+export type ReplayScoreVerificationReason = 'score-mismatch' | 'replay-invalid';
+export interface ReplayScoreVerificationResult {
+    readonly ok: boolean;
+    readonly reason?: ReplayScoreVerificationReason;
+    readonly verifiedScore?: number;
+}
+/**
+ * Code-free score re-run (M8.5). Re-runs the TRUSTED built-in runtime (from the
+ * deploy-time manifest) over the CLIENT's recorded inputs and reads the score
+ * the runtime produces — no game `step`/`extractScore` and no vm sandbox. The
+ * runtime's initial state is seeded from the trusted descriptor; the client's
+ * `replay.initialState`/checksums are ignored. Rejects `'replay-invalid'` when
+ * the replay's identity fields don't match the manifest or the inputs cannot be
+ * re-run, `'score-mismatch'` on a clean re-run whose score differs from
+ * `submittedScore`. Fails closed: any thrown error becomes `'replay-invalid'`.
+ */
+export declare function verifyReplayScoreAgainstTrustedRuntime(input: {
+    readonly manifest: DeterministicReplayVerificationManifest;
+    readonly replay: ReplayFile;
+    readonly submittedScore: number;
+}): ReplayScoreVerificationResult;
 export declare function minimizeDeterministicReplayDesync(expected: DeterministicReplayBundle, actual: DeterministicReplayBundle): DeterministicReplayBundleMismatch | undefined;
 export declare function minimizeDeterministicReplayDesyncBundle(expected: DeterministicReplayBundle, actual: DeterministicReplayBundle): DeterministicReplayDesyncMinimization | undefined;
 export declare function createDeterministicReplayDebugTables(events: readonly RecordedDebugEvent[]): DeterministicReplayDebugTables;

package/dist/replay-bundle.js

@@ -386,6 +386,103 @@ export function verifyDeterministicSelfContainedFrameRuntimeReplayBundle(bundle,
         beforeFrame: deterministicReplayRuntimeBeforeFrame(manifest.beforeFrameId),
     });
 }
+/**
+ * Code-free score re-run (M8.5). Re-runs the TRUSTED built-in runtime (from the
+ * deploy-time manifest) over the CLIENT's recorded inputs and reads the score
+ * the runtime produces — no game `step`/`extractScore` and no vm sandbox. The
+ * runtime's initial state is seeded from the trusted descriptor; the client's
+ * `replay.initialState`/checksums are ignored. Rejects `'replay-invalid'` when
+ * the replay's identity fields don't match the manifest or the inputs cannot be
+ * re-run, `'score-mismatch'` on a clean re-run whose score differs from
+ * `submittedScore`. Fails closed: any thrown error becomes `'replay-invalid'`.
+ */
+export function verifyReplayScoreAgainstTrustedRuntime(input) {
+    const { manifest, replay, submittedScore } = input;
+    if (replay.deterministicVersion !== manifest.deterministicVersion ||
+        replay.inputSchemaId !== manifest.inputSchemaId ||
+        replay.stateSchemaId !== manifest.stateSchemaId) {
+        return { ok: false, reason: 'replay-invalid' };
+    }
+    let verifiedScore;
+    try {
+        verifiedScore = runTrustedReplayRuntimeScore(manifest, replay);
+    }
+    catch {
+        return { ok: false, reason: 'replay-invalid' };
+    }
+    if (verifiedScore === submittedScore) {
+        return { ok: true, verifiedScore };
+    }
+    return { ok: false, reason: 'score-mismatch', verifiedScore };
+}
+function runTrustedReplayRuntimeScore(manifest, replay) {
+    const runtime = manifest.sparse === true
+        ? createDeterministicSparseSetFrameRuntime(manifest.descriptor, manifest.seed)
+        : createDeterministicFrameRuntime(manifest.descriptor, manifest.seed);
+    seedTrustedReplayRuntimeState(runtime, manifest.descriptor, manifest.systemId);
+    const systems = deterministicReplayRuntimeSystems(manifest.systemId);
+    const beforeFrame = deterministicReplayRuntimeBeforeFrame(manifest.beforeFrameId);
+    const inputByFrame = new Map(replay.inputFrames.map((frame) => [frame.frame, frame.inputs]));
+    const commandByFrame = new Map((replay.commandHistory ?? []).map((frame) => [frame.frame, frame.commands]));
+    let maxFrame = -1;
+    for (const frame of inputByFrame.keys()) {
+        maxFrame = frame > maxFrame ? frame : maxFrame;
+    }
+    for (const frame of commandByFrame.keys()) {
+        maxFrame = frame > maxFrame ? frame : maxFrame;
+    }
+    for (let frame = 0; frame <= maxFrame; frame += 1) {
+        beforeFrame?.(runtime, frame, inputByFrame.get(frame) ?? [], commandByFrame.get(frame) ?? []);
+        runtime.step(systems);
+    }
+    return readTrustedReplayRuntimeScore(runtime, manifest.systemId);
+}
+function seedTrustedReplayRuntimeState(runtime, descriptor, systemId) {
+    if (systemId === 'project-game-state-runtime-replay-v1') {
+        runtime.setSingleton('gameState', trustedReplayRuntimeDefaultGameState(descriptor));
+        runtime.setSingleton('runtimeReplayState', { value: 0, inputDelta: 0, commandDelta: 0 });
+        return;
+    }
+    runtime.setSingleton('score', { value: 0, inputDelta: 0, commandDelta: 0 });
+}
+function readTrustedReplayRuntimeScore(runtime, systemId) {
+    const singletons = runtime.snapshot().singletonComponents;
+    if (systemId === 'project-game-state-runtime-replay-v1') {
+        const gameState = singletons.gameState;
+        if (gameState === undefined || typeof gameState.score !== 'number') {
+            throw new Error('Trusted replay runtime produced no gameState.score');
+        }
+        return gameState.score;
+    }
+    const score = singletons.score;
+    /* istanbul ignore next -- defensive: the trusted score runtime always keeps a numeric score singleton. */
+    if (score === undefined || typeof score.value !== 'number') {
+        throw new Error('Trusted replay runtime produced no score.value');
+    }
+    return score.value;
+}
+function trustedReplayRuntimeDefaultGameState(descriptor) {
+    const gameState = descriptor.components.find((component) => component.id === 'gameState' && component.singleton === true);
+    if (gameState === undefined) {
+        return {};
+    }
+    return Object.fromEntries(gameState.fields.map((field) => [
+        field.name,
+        field.defaultValue ?? trustedReplayRuntimeDefaultValueForKind(field.kind),
+    ]));
+}
+function trustedReplayRuntimeDefaultValueForKind(kind) {
+    if (kind.endsWith('[]')) {
+        return [];
+    }
+    if (kind === 'bool') {
+        return false;
+    }
+    if (kind === 'string' || kind === 'asset-ref' || kind === 'entity-ref') {
+        return '';
+    }
+    return 0;
+}
 function findDuplicateFrameRecord(bundle) {
     return findDuplicateFrame(bundle.inputHistory.map((frame) => frame.frame), 'inputHistory')
         ?? findDuplicateFrame(bundle.commandHistory.map((frame) => frame.frame), 'commandHistory')
@@ -1237,23 +1334,13 @@ function deterministicReplayRuntimeBeforeFrame(beforeFrameId) {
             return injectProjectGameStateRuntimeReplayFrame;
     }
 }
-function injectScoreRuntimeReplayFrame(runtime, _frame, inputs, commands) {
-    const inputDelta = inputs.reduce((sum, input) => isReplayRecord(input) && typeof input.dx === 'number' ? sum + input.dx : sum, 0);
-    const commandDelta = commands.reduce((sum, command) => {
-        if (!isReplayRecord(command) || !isReplayRecord(command.payload) || typeof command.payload.power !== 'number') {
-            return sum;
-        }
-        return sum + command.payload.power;
-    }, 0);
-    const score = runtime.snapshot().singletonComponents.score ?? { value: 0 };
-    runtime.setSingleton('score', {
-        value: Number(score.value ?? 0),
-        inputDelta,
-        commandDelta,
-    });
-}
-function injectProjectGameStateRuntimeReplayFrame(runtime, frame, inputs, commands) {
-    const inputDelta = inputs.reduce((sum, input) => {
+// The built-in-runtime input/command delta rules. These MUST stay identical to
+// the copies certify runs with (cli.ts `projectReplayInputDelta` /
+// `projectReplayCommandDelta`) — the trusted server re-run reads the score those
+// rules produce, so any divergence would falsely reject an honest replay whose
+// inputs use `moveX`/`points` (or commands use `slot`) instead of `dx`/`power`.
+function replayRuntimeInputDelta(inputs) {
+    return inputs.reduce((sum, input) => {
         if (!isReplayRecord(input)) {
             return sum;
         }
@@ -1263,9 +1350,14 @@ function injectProjectGameStateRuntimeReplayFrame(runtime, frame, inputs, comman
         if (typeof input.moveX === 'number') {
             return sum + input.moveX;
         }
+        if (typeof input.points === 'number') {
+            return sum + input.points;
+        }
         return sum;
     }, 0);
-    const commandDelta = commands.reduce((sum, command) => {
+}
+function replayRuntimeCommandDelta(commands) {
+    return commands.reduce((sum, command) => {
         if (!isReplayRecord(command) || !isReplayRecord(command.payload)) {
             return sum;
         }
@@ -1277,6 +1369,20 @@ function injectProjectGameStateRuntimeReplayFrame(runtime, frame, inputs, comman
         }
         return sum;
     }, 0);
+}
+function injectScoreRuntimeReplayFrame(runtime, _frame, inputs, commands) {
+    const inputDelta = replayRuntimeInputDelta(inputs);
+    const commandDelta = replayRuntimeCommandDelta(commands);
+    const score = runtime.snapshot().singletonComponents.score ?? { value: 0 };
+    runtime.setSingleton('score', {
+        value: Number(score.value ?? 0),
+        inputDelta,
+        commandDelta,
+    });
+}
+function injectProjectGameStateRuntimeReplayFrame(runtime, frame, inputs, commands) {
+    const inputDelta = replayRuntimeInputDelta(inputs);
+    const commandDelta = replayRuntimeCommandDelta(commands);
     const state = runtime.snapshot().singletonComponents.runtimeReplayState ?? { value: 0 };
     runtime.setSingleton('runtimeReplayState', {
         value: Number(state.value ?? 0),
@@ -1454,8 +1560,8 @@ export const __replayBundleCoverageProof = {
                 builtInWrites.push(value);
             },
         };
-        deterministicReplayRuntimeBeforeFrame('score-input-command-delta-v1')?.(fakeRuntime, 0, [{}], [{}]);
-        deterministicReplayRuntimeBeforeFrame('project-game-state-input-command-delta-v1')?.(fakeRuntime, 0, [{ moveX: 2 }, {}], [{ payload: { slot: 1 } }, {}]);
+        deterministicReplayRuntimeBeforeFrame('score-input-command-delta-v1')?.(fakeRuntime, 0, [{ dx: 1 }, 5, { points: 2 }], [{ payload: { power: 3 } }, 7]);
+        deterministicReplayRuntimeBeforeFrame('project-game-state-input-command-delta-v1')?.(fakeRuntime, 0, [{ moveX: 2 }, {}], [{ payload: { slot: 1 } }, { payload: {} }]);
         const semanticFallbackBaseline = canonicalStringify({ frame: -1, positions: ['bad'], commandScore: 0 });
         const semanticFallbackFrame = canonicalStringify({ frame: 0, positions: [2], commandScore: 0 });
         const semanticFallback = verifySemanticReplay(createDeterministicReplayBundle({

package/dist/sample-scenes.js

@@ -658,6 +658,9 @@ function addSceneMetrics(sampleId, frame, seed, metrics) {
             add('teamScores', frame % 19 === 0);
             add('priorityResolutions', true);
             return;
+        // Intentionally kinematic (counter-based mechanics, not simulated). The
+        // physics-driven raycast-wheel vehicle lives in physics3d-vehicle.ts and is
+        // certified by the physics-rigid-vehicle fixture + builtin-rigid arena car.
         case 'vehicle':
             add('steeringFrames', true);
             add('accelerationFrames', frame % 2 === 0);

package/dist/sdk-offline.js

@@ -1,43 +1,17 @@
-import { createOfflineSession } from './offline-session.js';
 import { createSchemaArtifacts } from './schema-artifacts.js';
+import { buildDeterministicSession } from './session-build.js';
 export function createSyncplayOfflineRuntime(config) {
+    // Kept for getFrame()'s checksum projection; session construction is delegated
+    // to the shared builder so every consumer wires schema identity identically.
     const artifacts = createSchemaArtifacts(config.descriptor);
     const listeners = new Set();
     const playerCount = config.playerCount ?? config.descriptor.maxPlayers;
-    if (playerCount > config.descriptor.maxPlayers) {
-        throw new Error(`Offline runtime playerCount ${playerCount} exceeds descriptor maxPlayers ${config.descriptor.maxPlayers}`);
-    }
-    const session = createOfflineSession({
-        tickRate: config.descriptor.tickRate,
+    const session = buildDeterministicSession({
+        descriptor: config.descriptor,
         playerCount,
         initialState: config.initialState,
-        step: config.step,
         defaultInput: config.defaultInput,
-        // Use the content-hashed identity ids, not the author labels — replay
-        // compatibility must track the actual field shapes.
-        inputSchemaId: artifacts.descriptor.replayIdentity.inputSchemaId,
-        stateSchemaId: artifacts.descriptor.replayIdentity.stateSchemaId,
-        deterministicVersion: config.descriptor.deterministicVersion,
-        canonicalizeInput(input) {
-            return artifacts.canonicalizeInput(input);
-        },
-        // FULL declared state for replay initial-state and snapshots: the session
-        // RESTORES from these (rollback, late-join hydration), so they must carry
-        // every declared field. The checksum projection stays checksum-only below —
-        // wiring it here wiped every checksummed:false field to undefined on the
-        // first rollback, silently diverging from peers that never rolled back.
-        canonicalizeState(state) {
-            return artifacts.canonicalizeFullState(state);
-        },
-        serializeState(state) {
-            return artifacts.serializeFullState(state);
-        },
-        deserializeState(bytes) {
-            return artifacts.deserializeFullState(bytes);
-        },
-        checksum(state) {
-            return artifacts.checksumState(state);
-        },
+        step: config.step,
         randomSeed: config.randomSeed,
         snapshotBufferSize: config.snapshotBufferSize,
         checksumIntervalFrames: config.checksumIntervalFrames,

package/dist/sdk-session.d.ts

@@ -0,0 +1,47 @@
+import { type NetworkedClientTransport } from './networked-client.js';
+import type { DeterministicGameDescriptor } from './schema.js';
+import type { EncodedInput } from './input-authority.js';
+import type { DeterministicStep, ReplayFile } from './types.js';
+export type SyncplaySessionMode = 'offline' | 'networked';
+export interface SyncplaySessionConfig<State, Input> {
+    readonly descriptor: DeterministicGameDescriptor;
+    readonly initialState: State;
+    readonly defaultInput: Input;
+    readonly step: DeterministicStep<State, Input>;
+    /** Encode a game input to the wire form the authority relays. */
+    readonly encodeInput: (input: Input) => EncodedInput;
+    /** Decode a wire input; MUST map the neutral substitute (canonical null) to your default. */
+    readonly decodeInput: (encoded: EncodedInput) => Input;
+    /** Slots while offline (defaults to descriptor.maxPlayers). Networked player count comes from the server. */
+    readonly playerCount?: number;
+    /** Offline-only seed. Networked mode uses the server-supplied seed. */
+    readonly randomSeed?: number;
+    readonly maxPredictionTicks?: number;
+}
+export interface SyncplaySession<State, Input> {
+    readonly mode: SyncplaySessionMode;
+    /** Own slot: 0 while offline; server-assigned slot once networked. */
+    readonly slot: number;
+    /** The room code once networked (undefined while offline). */
+    readonly roomCode: string | undefined;
+    getState(): State;
+    setLocalInput(input: Input): void;
+    /** Advance by wall-clock delta: steps the offline sim, or paced-pumps the networked client. */
+    advance(deltaMs: number): void;
+    subscribe(listener: (state: State) => void): () => void;
+    /**
+     * Transition offline → networked against a live room. RESETS the simulation to
+     * the room's server-supplied seed at tick 0 (in-progress solo state is not
+     * carried over — see SYNCPLAY.md). Resolves once the server sends session-start.
+     */
+    openRoom(transport: OpenRoomTransport): Promise<void>;
+    exportReplay(): ReplayFile;
+    dispose(): void;
+}
+/** A room transport plus its shareable code (SyncplayRoomTransport satisfies this). */
+export interface OpenRoomTransport extends NetworkedClientTransport {
+    readonly roomCode?: string;
+    /** Leave the room / close the socket. Called on dispose so a promoted session frees its seat. */
+    close?(): void;
+}
+export declare function createSyncplaySession<State, Input>(config: SyncplaySessionConfig<State, Input>): SyncplaySession<State, Input>;

package/dist/sdk-session.js

@@ -0,0 +1,153 @@
+import { buildDeterministicSession } from './session-build.js';
+import { createNetworkedSyncplayClient, } from './networked-client.js';
+export function createSyncplaySession(config) {
+    const offlinePlayerCount = config.playerCount ?? config.descriptor.maxPlayers;
+    const listeners = new Set();
+    let disposed = false;
+    let mode = 'offline';
+    let session = buildDeterministicSession({
+        descriptor: config.descriptor,
+        playerCount: offlinePlayerCount,
+        initialState: config.initialState,
+        defaultInput: config.defaultInput,
+        step: config.step,
+        randomSeed: config.randomSeed,
+    });
+    let localInput = config.defaultInput;
+    let slot = 0;
+    let roomCode;
+    let client;
+    let networkTransport;
+    let opening = false;
+    let now = 0;
+    // Resolves the moment dispose() runs, so an in-flight openRoom stops awaiting
+    // session-start instead of hanging forever when the room never greets it.
+    let signalDisposed;
+    const disposedSignal = new Promise((resolve) => {
+        signalDisposed = resolve;
+    });
+    const assertLive = () => {
+        if (disposed)
+            throw new Error('SyncplaySession is disposed');
+    };
+    const notify = () => {
+        const state = session.getState();
+        for (const l of listeners)
+            l(state);
+    };
+    const api = {
+        get mode() {
+            return mode;
+        },
+        get slot() {
+            return slot;
+        },
+        get roomCode() {
+            return roomCode;
+        },
+        getState() {
+            assertLive();
+            return session.getState();
+        },
+        setLocalInput(input) {
+            assertLive();
+            localInput = input;
+        },
+        advance(deltaMs) {
+            assertLive();
+            if (mode === 'offline') {
+                session.setInput(slot, localInput);
+                if (session.update(deltaMs) > 0)
+                    notify();
+            }
+            else {
+                now += deltaMs;
+                client.pumpPaced(now);
+                notify();
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            listener(session.getState());
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        async openRoom(transport) {
+            assertLive();
+            // `opening` closes the window a concurrent call could slip through before
+            // `mode` flips (it only flips after the await): a session promotes once.
+            if (mode !== 'offline' || opening) {
+                throw new Error('SyncplaySession.openRoom already called — a session promotes to a room once');
+            }
+            opening = true;
+            // Publish the in-flight transport immediately so dispose() can tear it
+            // down even before session-start arrives.
+            networkTransport = transport;
+            let promoted = false;
+            try {
+                // Client construction is inside the try: it wires the transport and can
+                // decode a synchronously-delivered session-start, so a throw here must
+                // still clear `opening` and free the transport (else the session wedges
+                // — every later openRoom would hit the guard).
+                const built = createNetworkedSyncplayClient({
+                    transport,
+                    createSession: ({ seed, playerCount }) => {
+                        session = buildDeterministicSession({
+                            descriptor: config.descriptor,
+                            playerCount,
+                            initialState: config.initialState,
+                            step: config.step,
+                            defaultInput: config.defaultInput,
+                            randomSeed: seed,
+                        });
+                        return session;
+                    },
+                    localInputForTick: () => localInput,
+                    encodeInput: config.encodeInput,
+                    decodeInput: config.decodeInput,
+                    maxPredictionTicks: config.maxPredictionTicks,
+                });
+                // Lose the race to dispose() rather than hang if the room never greets.
+                await Promise.race([built.whenReady(), disposedSignal]);
+                // Disposed while awaiting session-start: dispose() already closed the
+                // transport — don't switch a dead object into networked mode.
+                if (disposed) {
+                    return;
+                }
+                client = built;
+                slot = built.slot;
+                roomCode = transport.roomCode;
+                mode = 'networked';
+                promoted = true;
+            }
+            catch (error) {
+                // Open failed BEFORE promotion: free the seat and reset so the caller
+                // can retry. Once promoted, the catch is unreachable — see notify below.
+                transport.close?.();
+                networkTransport = undefined;
+                throw error;
+            }
+            finally {
+                opening = false;
+            }
+            // Notify OUTSIDE the try: a throwing listener must not tear down an
+            // already-promoted session (it's networked; the join succeeded).
+            if (promoted)
+                notify();
+        },
+        exportReplay() {
+            assertLive();
+            return (client ?? session).exportReplay();
+        },
+        dispose() {
+            disposed = true;
+            listeners.clear();
+            // Closes both a promoted transport and one still awaiting session-start.
+            networkTransport?.close?.();
+            networkTransport = undefined;
+            signalDisposed?.();
+        },
+    };
+    return api;
+}

package/dist/session-build.d.ts

@@ -0,0 +1,21 @@
+import type { DeterministicGameDescriptor } from './schema.js';
+import type { DeterministicStep, OfflineSession, ReplayRecordingMode } from './types.js';
+export interface BuildDeterministicSessionConfig<State, Input> {
+    readonly descriptor: DeterministicGameDescriptor;
+    readonly playerCount: number;
+    readonly initialState: State;
+    readonly defaultInput: Input;
+    readonly step: DeterministicStep<State, Input>;
+    readonly randomSeed?: number;
+    readonly snapshotBufferSize?: number;
+    readonly checksumIntervalFrames?: number;
+    readonly maxCatchUpFrames?: number;
+    readonly replayRecordingMode?: ReplayRecordingMode;
+    readonly runtimeGuards?: boolean;
+}
+/**
+ * Construct an OfflineSession from a validated descriptor, wiring the
+ * content-hashed schema identity and full-state (de)serialization the same way
+ * for every consumer (offline runtime, unified session, networked createSession).
+ */
+export declare function buildDeterministicSession<State, Input>(config: BuildDeterministicSessionConfig<State, Input>): OfflineSession<State, Input>;

package/dist/session-build.js

@@ -0,0 +1,39 @@
+import { createOfflineSession } from './offline-session.js';
+import { createSchemaArtifacts } from './schema-artifacts.js';
+/**
+ * Construct an OfflineSession from a validated descriptor, wiring the
+ * content-hashed schema identity and full-state (de)serialization the same way
+ * for every consumer (offline runtime, unified session, networked createSession).
+ */
+export function buildDeterministicSession(config) {
+    const artifacts = createSchemaArtifacts(config.descriptor);
+    if (config.playerCount > config.descriptor.maxPlayers) {
+        throw new Error(`Session playerCount ${config.playerCount} exceeds descriptor maxPlayers ${config.descriptor.maxPlayers}`);
+    }
+    return createOfflineSession({
+        tickRate: config.descriptor.tickRate,
+        playerCount: config.playerCount,
+        initialState: config.initialState,
+        step: config.step,
+        defaultInput: config.defaultInput,
+        // Use the content-hashed identity ids, not the author labels — replay
+        // compatibility must track the actual field shapes.
+        inputSchemaId: artifacts.descriptor.replayIdentity.inputSchemaId,
+        stateSchemaId: artifacts.descriptor.replayIdentity.stateSchemaId,
+        deterministicVersion: config.descriptor.deterministicVersion,
+        canonicalizeInput: (input) => artifacts.canonicalizeInput(input),
+        // FULL declared state for replay initial-state and snapshots (rollback,
+        // late-join hydration restore from these): they must carry every declared
+        // field, not just the checksummed projection.
+        canonicalizeState: (state) => artifacts.canonicalizeFullState(state),
+        serializeState: (state) => artifacts.serializeFullState(state),
+        deserializeState: (bytes) => artifacts.deserializeFullState(bytes),
+        checksum: (state) => artifacts.checksumState(state),
+        randomSeed: config.randomSeed,
+        snapshotBufferSize: config.snapshotBufferSize,
+        checksumIntervalFrames: config.checksumIntervalFrames,
+        maxCatchUpFrames: config.maxCatchUpFrames,
+        replayRecordingMode: config.replayRecordingMode,
+        runtimeGuards: config.runtimeGuards,
+    });
+}