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

package/dist/schema.d.ts

@@ -0,0 +1,87 @@
+import type { TickRate } from './types.js';
+export type NumericMode = 'integer' | 'fixed-q16' | 'quantized-float' | 'render-only-float';
+export type CollectionOrdering = 'indexed' | 'sorted-key' | 'stable-id';
+export type InputFieldPolicy = 'repeat' | 'command';
+export type SchemaFieldKind = 'boolean' | 'button' | 'integer' | 'fixed-q16' | 'string' | 'bitfield' | 'player-slot' | 'asset-ref';
+export interface SchemaFieldDescriptor {
+    readonly name: string;
+    readonly kind: SchemaFieldKind;
+    readonly numericMode?: NumericMode;
+    readonly collectionOrdering?: CollectionOrdering;
+    readonly min?: number;
+    readonly max?: number;
+}
+export interface InputFieldDescriptor extends SchemaFieldDescriptor {
+    readonly policy: InputFieldPolicy;
+    readonly defaultValue: boolean | number | string;
+    readonly bitPacking?: {
+        readonly bits: number;
+        readonly signed?: boolean;
+    };
+}
+export interface StateFieldDescriptor extends SchemaFieldDescriptor {
+    readonly checksummed: boolean;
+}
+export interface EventDescriptor {
+    readonly id: string;
+    readonly payloadFields: readonly SchemaFieldDescriptor[];
+    readonly rollback: 'predicted' | 'verified-only';
+}
+export interface CommandChannelDescriptor {
+    readonly id: string;
+    readonly fields: readonly SchemaFieldDescriptor[];
+    readonly delivery: 'reliable' | 'unreliable';
+}
+export interface AssetDescriptor {
+    readonly id: string;
+    readonly fields: readonly SchemaFieldDescriptor[];
+}
+export interface PrototypeDescriptor {
+    readonly id: string;
+    readonly components: readonly string[];
+}
+export interface ConfigDescriptor {
+    readonly id: string;
+    readonly fields: readonly SchemaFieldDescriptor[];
+}
+export interface SystemDescriptor {
+    readonly id: string;
+}
+export interface DeterministicGameDescriptor {
+    readonly deterministicVersion: string;
+    readonly tickRate: TickRate;
+    readonly maxPlayers: number;
+    readonly input: {
+        readonly id: string;
+        readonly fields: readonly InputFieldDescriptor[];
+    };
+    readonly state: {
+        readonly id: string;
+        readonly fields: readonly StateFieldDescriptor[];
+    };
+    readonly commandChannels?: readonly CommandChannelDescriptor[];
+    readonly events?: readonly EventDescriptor[];
+    readonly assets?: readonly AssetDescriptor[];
+    readonly prototypes?: readonly PrototypeDescriptor[];
+    readonly config?: ConfigDescriptor;
+    readonly systems: readonly SystemDescriptor[];
+}
+export interface ValidatedDeterministicGameDescriptor extends DeterministicGameDescriptor {
+    readonly artifactId: string;
+    readonly replayIdentity: {
+        readonly deterministicVersion: string;
+        readonly tickRate: TickRate;
+        readonly maxPlayers: number;
+        readonly inputSchemaId: string;
+        readonly stateSchemaId: string;
+        readonly commandSchemaId: string;
+        readonly eventSchemaId: string;
+        readonly assetSchemaId: string;
+        readonly prototypeSchemaId: string;
+        readonly configSchemaId: string;
+        readonly systemOrderId: string;
+        readonly artifactId: string;
+    };
+}
+export declare function defineSyncplayGame(descriptor: DeterministicGameDescriptor): ValidatedDeterministicGameDescriptor;
+export declare function stableDescriptorId(prefix: string, value: unknown): string;

package/dist/schema.js

@@ -0,0 +1,315 @@
+import { canonicalStringify, defaultChecksum } from './canonical.js';
+import { SyncplayError } from './errors.js';
+const tickRates = [10, 20, 30, 60];
+const idPattern = /^[a-zA-Z0-9][a-zA-Z0-9._/@-]*$/;
+const numericModes = ['integer', 'fixed-q16', 'quantized-float', 'render-only-float'];
+const numericFieldKinds = ['integer', 'fixed-q16', 'bitfield', 'player-slot'];
+const collectionOrderings = ['indexed', 'sorted-key', 'stable-id'];
+export function defineSyncplayGame(descriptor) {
+    validateDescriptor(descriptor);
+    const eventSchemaId = descriptor.events === undefined ? 'events/none' : stableDescriptorId('events', descriptor.events);
+    const assetSchemaId = descriptor.assets === undefined ? 'assets/none' : stableDescriptorId('assets', descriptor.assets);
+    const commandSchemaId = descriptor.commandChannels === undefined ? 'commands/none' : stableDescriptorId('commands', descriptor.commandChannels);
+    const prototypeSchemaId = descriptor.prototypes === undefined ? 'prototypes/none' : stableDescriptorId('prototypes', descriptor.prototypes);
+    // Content-hash the input/state/config sub-ids like every other identity
+    // component: the author-declared label rides along, but editing the FIELDS
+    // without bumping the label must change the replay identity — otherwise a
+    // schema edit produces replays that verify as compatible and then diverge.
+    const configSchemaId = descriptor.config === undefined
+        ? 'config/none'
+        : `${descriptor.config.id}#${stableDescriptorId('config', descriptor.config)}`;
+    const inputSchemaId = `${descriptor.input.id}#${stableDescriptorId('input', descriptor.input)}`;
+    const stateSchemaId = `${descriptor.state.id}#${stableDescriptorId('state', descriptor.state)}`;
+    const systemOrderId = stableDescriptorId('systems', descriptor.systems.map((system) => system.id));
+    const identity = {
+        deterministicVersion: descriptor.deterministicVersion,
+        tickRate: descriptor.tickRate,
+        maxPlayers: descriptor.maxPlayers,
+        inputSchemaId,
+        stateSchemaId,
+        commandSchemaId,
+        eventSchemaId,
+        assetSchemaId,
+        prototypeSchemaId,
+        configSchemaId,
+        systemOrderId,
+        artifactId: '',
+    };
+    const artifactId = stableDescriptorId('game', {
+        ...descriptor,
+        commandSchemaId,
+        eventSchemaId,
+        assetSchemaId,
+        prototypeSchemaId,
+        configSchemaId,
+        systemOrderId,
+    });
+    return {
+        ...descriptor,
+        artifactId,
+        replayIdentity: {
+            ...identity,
+            artifactId,
+        },
+    };
+}
+export function stableDescriptorId(prefix, value) {
+    return `${prefix}/${defaultChecksum(value)}`;
+}
+function validateDescriptor(descriptor) {
+    validateId('deterministicVersion', descriptor.deterministicVersion);
+    if (!tickRates.includes(descriptor.tickRate)) {
+        throwSchemaError('tickRate must be one of 10, 20, 30, or 60', 'schema.tick-rate');
+    }
+    if (!Number.isInteger(descriptor.maxPlayers) || descriptor.maxPlayers < 1 || descriptor.maxPlayers > 128) {
+        throwSchemaError('maxPlayers must be an integer between 1 and 128', 'schema.max-players');
+    }
+    validateId('input.id', descriptor.input.id);
+    validateInputFields(descriptor.input.fields, descriptor.maxPlayers);
+    validateId('state.id', descriptor.state.id);
+    validateStateFields(descriptor.state.fields);
+    validateCommandChannels(descriptor.commandChannels ?? []);
+    validateEvents(descriptor.events ?? []);
+    validateAssets(descriptor.assets ?? []);
+    validatePrototypes(descriptor.prototypes ?? []);
+    if (descriptor.config !== undefined) {
+        validateId('config.id', descriptor.config.id);
+        validateFields('config.fields', descriptor.config.fields);
+        rejectButtonFields('config.fields', descriptor.config.fields);
+    }
+    validateNamedDescriptors('systems', descriptor.systems);
+    if (descriptor.systems.length === 0) {
+        throwSchemaError('At least one stateless system id is required', 'schema.systems-empty');
+    }
+    canonicalStringify(descriptor);
+}
+function validateCommandChannels(channels) {
+    validateNamedDescriptors('commandChannels', channels);
+    for (const channel of channels) {
+        if (channel.delivery !== 'reliable' && channel.delivery !== 'unreliable') {
+            throwSchemaError(`Command channel ${channel.id} has invalid delivery`, 'schema.command-delivery');
+        }
+        validateFields(`commandChannels.${channel.id}.fields`, channel.fields);
+        rejectButtonFields(`commandChannels.${channel.id}.fields`, channel.fields);
+    }
+}
+function validateEvents(events) {
+    validateNamedDescriptors('events', events);
+    for (const event of events) {
+        if (event.rollback !== 'predicted' && event.rollback !== 'verified-only') {
+            throwSchemaError(`Event ${event.id} has invalid rollback mode`, 'schema.event-rollback');
+        }
+        validateFields(`events.${event.id}.payloadFields`, event.payloadFields);
+        rejectButtonFields(`events.${event.id}.payloadFields`, event.payloadFields);
+    }
+}
+function validateAssets(assets) {
+    validateNamedDescriptors('assets', assets);
+    for (const asset of assets) {
+        validateFields(`assets.${asset.id}.fields`, asset.fields);
+        rejectButtonFields(`assets.${asset.id}.fields`, asset.fields);
+    }
+}
+function validatePrototypes(prototypes) {
+    validateNamedDescriptors('prototypes', prototypes);
+    for (const prototype of prototypes) {
+        if (prototype.components.length === 0) {
+            throwSchemaError(`Prototype ${prototype.id} must include at least one component`, 'schema.prototype-components');
+        }
+        const components = new Set();
+        for (const component of prototype.components) {
+            validateId(`prototypes.${prototype.id}.component`, component);
+            if (components.has(component)) {
+                throwSchemaError(`Prototype ${prototype.id} contains duplicate component ${component}`, 'schema.prototype-duplicate-component');
+            }
+            components.add(component);
+        }
+    }
+}
+function validateInputFields(fields, maxPlayers) {
+    validateFields('input.fields', fields);
+    for (const field of fields) {
+        if (field.policy !== 'repeat' && field.policy !== 'command') {
+            throwSchemaError(`Input field ${field.name} has invalid policy`, 'schema.input-policy');
+        }
+        if (field.kind === 'bitfield'
+            && (field.bitPacking === undefined
+                || !Number.isInteger(field.bitPacking.bits)
+                || field.bitPacking.bits < 1
+                || field.bitPacking.bits > 32)) {
+            throwSchemaError(`Input bitfield ${field.name} requires 1 to 32 packing bits`, 'schema.bit-packing');
+        }
+        if (field.kind === 'button' && field.bitPacking !== undefined && (field.bitPacking.bits !== 1 || field.bitPacking.signed === true)) {
+            throwSchemaError(`Input button ${field.name} bitPacking must be one unsigned bit`, 'schema.bit-packing');
+        }
+        if (field.kind !== 'button'
+            && field.kind !== 'bitfield'
+            && field.kind !== 'integer'
+            && field.kind !== 'player-slot'
+            && field.bitPacking !== undefined) {
+            throwSchemaError(`Input ${field.name} bitPacking is only valid on numeric or button fields`, 'schema.bit-packing');
+        }
+        if (field.bitPacking !== undefined && typeof field.bitPacking.signed !== 'boolean' && field.bitPacking.signed !== undefined) {
+            throwSchemaError(`Input bitfield ${field.name} signed packing flag must be boolean`, 'schema.bit-packing');
+        }
+        validateInputDefaultValue(field);
+        const playerSlotDefault = Number(field.defaultValue);
+        // Validate against the game's actual maxPlayers, not the platform cap of
+        // 128 — the runtime canonicalizer rejects `value >= maxPlayers`
+        // (schema-artifacts.player-slot), so a default that only passes the 128
+        // check here would throw in the hot path the first time it is substituted.
+        if (field.kind === 'player-slot' && (playerSlotDefault < 0 || playerSlotDefault >= maxPlayers)) {
+            throwSchemaError(`Input player-slot ${field.name} defaultValue must be within [0, maxPlayers)`, 'schema.input-default');
+        }
+    }
+}
+function validateStateFields(fields) {
+    validateFields('state.fields', fields);
+    for (const field of fields) {
+        if (field.checksummed !== true && field.checksummed !== false) {
+            throwSchemaError(`State field ${field.name} must declare checksum participation`, 'schema.state-checksum');
+        }
+        if (field.numericMode === 'render-only-float' && field.checksummed) {
+            throwSchemaError(`Render-only float field ${field.name} cannot be checksummed`, 'schema.render-float-checksum');
+        }
+        if (field.kind === 'button') {
+            throwSchemaError(`State field ${field.name} cannot use input-only button kind`, 'schema.button-state');
+        }
+    }
+    // With zero checksummed fields the state projection is {} for every frame,
+    // so checksums are a single constant — desync detection and replay
+    // verification would silently compare always-equal values. Reject at
+    // definition time (after per-field validation, so specific field errors
+    // surface first): a determinism contract needs at least one observed field.
+    if (!fields.some((field) => field.checksummed === true)) {
+        throwSchemaError('At least one state field must be checksummed', 'schema.state-no-checksum');
+    }
+}
+function rejectButtonFields(label, fields) {
+    for (const field of fields) {
+        if (field.kind === 'button') {
+            throwSchemaError(`${label}.${field.name} cannot use input-only button kind`, 'schema.button-non-input');
+        }
+    }
+}
+function validateFields(label, fields) {
+    if (fields.length === 0) {
+        throwSchemaError(`${label} must not be empty`, 'schema.empty-fields');
+    }
+    const names = new Set();
+    for (const field of fields) {
+        validateId(`${label}.name`, field.name);
+        if (names.has(field.name)) {
+            throwSchemaError(`${label} contains duplicate field ${field.name}`, 'schema.duplicate-field');
+        }
+        names.add(field.name);
+        validateFieldKind(field);
+        validateNumericMode(field);
+        validateCollectionOrdering(field);
+        validateRange(field);
+        if (field.min !== undefined && field.max !== undefined && field.max < field.min) {
+            throwSchemaError(`Field ${field.name} has max below min`, 'schema.invalid-range');
+        }
+    }
+}
+function validateRange(field) {
+    if (field.min !== undefined && (typeof field.min !== 'number' || !Number.isFinite(field.min))) {
+        throwSchemaError(`Field ${field.name} min must be numeric`, 'schema.invalid-range');
+    }
+    if (field.max !== undefined && (typeof field.max !== 'number' || !Number.isFinite(field.max))) {
+        throwSchemaError(`Field ${field.name} max must be numeric`, 'schema.invalid-range');
+    }
+    if ((field.min !== undefined || field.max !== undefined) && !numericFieldKinds.includes(field.kind)) {
+        throwSchemaError(`Field ${field.name} range is only valid on numeric fields`, 'schema.invalid-range');
+    }
+}
+function validateNumericMode(field) {
+    if (field.numericMode === undefined) {
+        return;
+    }
+    if (!numericModes.includes(field.numericMode)) {
+        throwSchemaError(`Field ${field.name} has invalid numericMode`, 'schema.numeric-mode');
+    }
+    if (!numericFieldKinds.includes(field.kind)) {
+        throwSchemaError(`Field ${field.name} numericMode is only valid on numeric fields`, 'schema.numeric-mode');
+    }
+    if (field.kind === 'fixed-q16' && field.numericMode !== 'fixed-q16' && field.numericMode !== 'quantized-float' && field.numericMode !== 'render-only-float') {
+        throwSchemaError(`Field ${field.name} fixed-q16 requires fixed numericMode`, 'schema.numeric-mode');
+    }
+    if ((field.kind === 'integer' || field.kind === 'bitfield' || field.kind === 'player-slot') && field.numericMode !== 'integer') {
+        throwSchemaError(`Field ${field.name} integer field requires integer numericMode`, 'schema.numeric-mode');
+    }
+}
+function validateCollectionOrdering(field) {
+    if (field.collectionOrdering === undefined) {
+        return;
+    }
+    if (!collectionOrderings.includes(field.collectionOrdering)) {
+        throwSchemaError(`Field ${field.name} has invalid collectionOrdering`, 'schema.collection-ordering');
+    }
+    // Scalar collection fields have no record ids to sort by — accepting a
+    // contract the canonicalizer cannot enforce is worse than rejecting it.
+    // Reintroduce alongside record-item collections.
+    if (field.collectionOrdering === 'stable-id') {
+        throwSchemaError(`Field ${field.name} collectionOrdering 'stable-id' is not supported on scalar collections (use 'indexed' or 'sorted-key')`, 'schema.collection-ordering');
+    }
+}
+function validateFieldKind(field) {
+    switch (field.kind) {
+        case 'boolean':
+        case 'button':
+        case 'integer':
+        case 'fixed-q16':
+        case 'string':
+        case 'bitfield':
+        case 'player-slot':
+        case 'asset-ref':
+            return;
+        default:
+            throwSchemaError(`Unsupported field kind ${field.kind}`, 'schema.field-kind');
+    }
+}
+function validateInputDefaultValue(field) {
+    if (field.kind === 'boolean' || field.kind === 'button') {
+        if (typeof field.defaultValue !== 'boolean') {
+            throwSchemaError(`Input ${field.kind} ${field.name} requires boolean defaultValue`, 'schema.input-default');
+        }
+        return;
+    }
+    if (field.kind === 'integer' || field.kind === 'bitfield' || field.kind === 'player-slot') {
+        if (typeof field.defaultValue !== 'number' || !Number.isInteger(field.defaultValue)) {
+            throwSchemaError(`Input ${field.kind} ${field.name} requires integer defaultValue`, 'schema.input-default');
+        }
+        return;
+    }
+    if (field.kind === 'fixed-q16') {
+        if (typeof field.defaultValue !== 'number' || !Number.isInteger(field.defaultValue)) {
+            throwSchemaError(`Input fixed-q16 ${field.name} requires quantized integer defaultValue`, 'schema.input-default');
+        }
+        return;
+    }
+    /* istanbul ignore else -- validateFieldKind rejects unsupported input field kinds before default validation. */
+    if (field.kind === 'string' || field.kind === 'asset-ref') {
+        if (typeof field.defaultValue !== 'string') {
+            throwSchemaError(`Input ${field.kind} ${field.name} requires string defaultValue`, 'schema.input-default');
+        }
+    }
+}
+function validateNamedDescriptors(label, descriptors) {
+    const ids = new Set();
+    for (const descriptor of descriptors) {
+        validateId(`${label}.id`, descriptor.id);
+        if (ids.has(descriptor.id)) {
+            throwSchemaError(`${label} contains duplicate id ${descriptor.id}`, 'schema.duplicate-id');
+        }
+        ids.add(descriptor.id);
+    }
+}
+function validateId(label, value) {
+    if (typeof value !== 'string' || value.length === 0 || !idPattern.test(value)) {
+        throwSchemaError(`${label} must be a stable non-empty id`, 'schema.invalid-id');
+    }
+}
+function throwSchemaError(message, code) {
+    throw new SyncplayError(message, { code });
+}

package/dist/sdk-offline.d.ts

@@ -0,0 +1,34 @@
+import type { DeterministicGameDescriptor } from './schema.js';
+import type { DeterministicStep, OfflineSession, ReplayFile, ReplayRecordingMode } from './types.js';
+export interface DeterministicOfflineRuntimeConfig<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;
+}
+export interface DeterministicOfflineFrame<State> {
+    readonly mode: 'offline';
+    readonly frame: number;
+    readonly predictedFrame: number;
+    readonly verifiedFrame: number;
+    readonly state: State;
+    readonly checksum: string;
+}
+export interface DeterministicOfflineRuntime<State, Input> {
+    readonly mode: 'offline';
+    readonly session: OfflineSession<State, Input>;
+    getFrame(): DeterministicOfflineFrame<State>;
+    setInput(slot: number, input: Input): void;
+    update(deltaMs: number): number;
+    stepFrames(count: number): void;
+    subscribe(listener: (frame: DeterministicOfflineFrame<State>) => void): () => void;
+    exportReplay(): ReplayFile;
+}
+export declare function createSyncplayOfflineRuntime<State, Input>(config: DeterministicOfflineRuntimeConfig<State, Input>): DeterministicOfflineRuntime<State, Input>;

package/dist/sdk-offline.js

@@ -0,0 +1,96 @@
+import { createOfflineSession } from './offline-session.js';
+import { createSchemaArtifacts } from './schema-artifacts.js';
+export function createSyncplayOfflineRuntime(config) {
+    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,
+        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);
+        },
+        randomSeed: config.randomSeed,
+        snapshotBufferSize: config.snapshotBufferSize,
+        checksumIntervalFrames: config.checksumIntervalFrames,
+        maxCatchUpFrames: config.maxCatchUpFrames,
+        replayRecordingMode: config.replayRecordingMode,
+        runtimeGuards: config.runtimeGuards,
+    });
+    const runtime = {
+        mode: 'offline',
+        session,
+        getFrame() {
+            const state = session.getState();
+            return {
+                mode: 'offline',
+                frame: session.currentFrame,
+                predictedFrame: session.currentFrame,
+                verifiedFrame: session.currentFrame,
+                state,
+                checksum: artifacts.checksumState(state),
+            };
+        },
+        setInput(slot, input) {
+            session.setInput(slot, input);
+        },
+        update(deltaMs) {
+            const advanced = session.update(deltaMs);
+            if (advanced > 0) {
+                notify();
+            }
+            return advanced;
+        },
+        stepFrames(count) {
+            session.stepFrames(count);
+            if (count > 0) {
+                notify();
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            listener(runtime.getFrame());
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        exportReplay() {
+            return session.exportReplay();
+        },
+    };
+    function notify() {
+        const frame = runtime.getFrame();
+        for (const listener of listeners) {
+            listener(frame);
+        }
+    }
+    return runtime;
+}

package/dist/session-promotion.d.ts

@@ -0,0 +1,26 @@
+import type { DeterministicSessionConfig, OfflineSession } from './types.js';
+/**
+ * Start-from-snapshot session promotion (practice → online, Quantum 3.0.5
+ * parity): freeze a running offline session into a self-describing blob, then
+ * hydrate a FRESH session from it with frame numbering continuing where the
+ * source left off.
+ *
+ * The blob is the same versioned `DeterministicStateSnapshot` envelope
+ * (`encodeDeterministicStateSnapshot`, `v: 1`) that the snapshot late-join
+ * transfer path ships, so it is wire-compatible with the existing
+ * snapshot-offer/chunk/complete envelopes.
+ *
+ * HONESTY NOTE — the online half is protocol work that is NOT done here.
+ * Seeding a NETWORKED match from a promoted snapshot requires the authority to
+ * accept an initial snapshot at session start (today the authority only brokers
+ * snapshots for late-joiners into an already-running match, and networked
+ * clients always start from tick 0 of the room descriptor). Until that
+ * protocol lands, promotion works offline-to-offline: practice session →
+ * `exportPromotionSnapshot` → `createSessionFromPromotionSnapshot` on any peer
+ * running the same game build.
+ *
+ * The hydrated session cannot export a replay (its history does not start at
+ * tick 0) — `exportReplay()` throws, per the `restoreSnapshot` contract.
+ */
+export declare function exportPromotionSnapshot<State, Input>(session: OfflineSession<State, Input>, frame?: number): string;
+export declare function createSessionFromPromotionSnapshot<State, Input>(config: DeterministicSessionConfig<State, Input>, blob: string): OfflineSession<State, Input>;

package/dist/session-promotion.js

@@ -0,0 +1,70 @@
+import { canonicalize } from './canonical.js';
+import { SyncplayError, invariant } from './errors.js';
+import { createOfflineSession } from './offline-session.js';
+import { base64ToBytes, bytesToBase64, encodeDeterministicStateSnapshot, decodeDeterministicStateSnapshot, } from './session-snapshot.js';
+/**
+ * Start-from-snapshot session promotion (practice → online, Quantum 3.0.5
+ * parity): freeze a running offline session into a self-describing blob, then
+ * hydrate a FRESH session from it with frame numbering continuing where the
+ * source left off.
+ *
+ * The blob is the same versioned `DeterministicStateSnapshot` envelope
+ * (`encodeDeterministicStateSnapshot`, `v: 1`) that the snapshot late-join
+ * transfer path ships, so it is wire-compatible with the existing
+ * snapshot-offer/chunk/complete envelopes.
+ *
+ * HONESTY NOTE — the online half is protocol work that is NOT done here.
+ * Seeding a NETWORKED match from a promoted snapshot requires the authority to
+ * accept an initial snapshot at session start (today the authority only brokers
+ * snapshots for late-joiners into an already-running match, and networked
+ * clients always start from tick 0 of the room descriptor). Until that
+ * protocol lands, promotion works offline-to-offline: practice session →
+ * `exportPromotionSnapshot` → `createSessionFromPromotionSnapshot` on any peer
+ * running the same game build.
+ *
+ * The hydrated session cannot export a replay (its history does not start at
+ * tick 0) — `exportReplay()` throws, per the `restoreSnapshot` contract.
+ */
+export function exportPromotionSnapshot(session, frame) {
+    const targetFrame = frame ?? session.currentFrame;
+    invariant(Number.isInteger(targetFrame) && targetFrame >= 1, 'Promotion export requires a stepped frame (>= 1): the v1 snapshot envelope encodes tick = frame - 1', 'promotion.invalid-frame');
+    const snapshot = session.getSnapshot(targetFrame);
+    if (snapshot === undefined) {
+        throw new SyncplayError(`No snapshot buffered for frame ${targetFrame} — it may have been evicted from the rolling buffer`, { code: 'promotion.missing-snapshot', frame: targetFrame });
+    }
+    return encodeDeterministicStateSnapshot({
+        v: 1,
+        tick: targetFrame - 1,
+        sessionFrame: targetFrame,
+        stateBytes: bytesToBase64(snapshot.stateBytes),
+        randomState: snapshot.randomState,
+        stateChecksum: snapshot.checksum,
+        // Session inputs are canonical by construction (cloneCanonical on setInput).
+        confirmedInputs: snapshot.inputs.map((input) => canonicalize(input)),
+    });
+}
+export function createSessionFromPromotionSnapshot(config, blob) {
+    const decoded = decodeDeterministicStateSnapshot(blob);
+    if (!decoded.ok) {
+        throw new SyncplayError(`Promotion snapshot rejected: ${decoded.reason}`, {
+            code: 'promotion.invalid-snapshot',
+        });
+    }
+    const snapshot = decoded.snapshot;
+    invariant(snapshot.confirmedInputs.length === config.playerCount, `Promotion snapshot carries ${snapshot.confirmedInputs.length} input slots but config.playerCount is ${config.playerCount}`, 'promotion.player-count-mismatch');
+    const session = createOfflineSession(config);
+    session.restoreSnapshot({
+        frame: snapshot.sessionFrame,
+        stateBytes: base64ToBytes(snapshot.stateBytes),
+        randomState: snapshot.randomState,
+        inputs: snapshot.confirmedInputs.map(
+        // NOT `??`: a hydrator returning null (the canonical neutral) must win
+        // over the raw recorded value (adversarial-review LOW).
+        (recorded) => (config.hydrateInput !== undefined ? config.hydrateInput(recorded) : recorded)),
+    });
+    const restored = session.getSnapshot(session.currentFrame);
+    if (restored === undefined || restored.checksum !== snapshot.stateChecksum) {
+        throw new SyncplayError('Promotion snapshot checksum mismatch after hydration — the game build or state bytes do not match the exporter', { code: 'promotion.checksum-mismatch', frame: snapshot.sessionFrame });
+    }
+    return session;
+}