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

package/dist/asset-cooking.d.ts

@@ -0,0 +1,82 @@
+import { type DeterministicFrameRuntimeDescriptor } from './engine-runtime.js';
+export interface DeterministicAssetSource {
+    readonly schemaVersion?: number;
+    readonly engineVersion?: string;
+    readonly dependencies?: readonly DeterministicAssetDependency[];
+    readonly assets: readonly DeterministicAssetRecord[];
+}
+export interface DeterministicAssetDependency {
+    readonly name: string;
+    readonly version: string;
+}
+export interface DeterministicAssetRecord {
+    readonly id: string;
+    readonly type?: string;
+    readonly references?: readonly string[];
+    readonly prototype?: boolean;
+    readonly [key: string]: unknown;
+}
+export interface DeterministicCookedAsset {
+    readonly id: string;
+    readonly type: string;
+    readonly hash: string;
+    readonly data: unknown;
+}
+export interface DeterministicAssetCookManifest {
+    readonly schemaVersion: 1;
+    readonly schemaHash: string;
+    readonly engineVersion: string;
+    readonly dependencyHash: string;
+    readonly dependencies: readonly DeterministicAssetDependency[];
+    readonly assetDbHash: string;
+    readonly lookupHash: string;
+    readonly prototypeIds: readonly string[];
+    readonly assetCount: number;
+    readonly assets: readonly {
+        readonly id: string;
+        readonly type: string;
+        readonly hash: string;
+    }[];
+}
+export interface DeterministicAssetCookResult {
+    readonly manifest: DeterministicAssetCookManifest;
+    readonly cookedAssets: readonly DeterministicCookedAsset[];
+    readonly bytes: string;
+}
+export interface DeterministicPrototypeEntity {
+    readonly entityId: number;
+    readonly prototypeId: string;
+    readonly assetDbHash: string;
+    readonly components: unknown;
+}
+export interface DeterministicPrototypeMaterializationOptions {
+    readonly startEntityId?: number;
+    readonly componentOverrides?: unknown;
+}
+export interface DeterministicMapMaterializationResult {
+    readonly mapId: string;
+    readonly assetDbHash: string;
+    readonly mapBakeHash: string;
+    readonly spawnCount: number;
+    readonly materializedEntityCount: number;
+    readonly prototypeIds: readonly string[];
+    readonly materializedEntities: readonly DeterministicPrototypeEntity[];
+    readonly checksum: string;
+}
+export interface DeterministicPrototypeRuntimeValidationResult {
+    readonly prototypeId: string;
+    readonly materializedEntityCount: number;
+    readonly injectedComponentCount: number;
+    readonly descriptorComponentCount: number;
+    readonly runtimeSnapshotChecksum: string;
+    readonly checksum: string;
+}
+export declare function cookDeterministicAssets(source: DeterministicAssetSource): DeterministicAssetCookResult;
+export declare function stableAssetCookJson(result: DeterministicAssetCookResult): string;
+export declare function materializePrototypeEntities(cooked: DeterministicAssetCookResult, prototypeId: string, count: number, options?: DeterministicPrototypeMaterializationOptions): readonly DeterministicPrototypeEntity[];
+export declare function materializeDeterministicMapEntities(cooked: DeterministicAssetCookResult, mapId: string, options?: DeterministicPrototypeMaterializationOptions): DeterministicMapMaterializationResult;
+export declare function validatePrototypeEntitiesAgainstFrameRuntime(cooked: DeterministicAssetCookResult, prototypeId: string, descriptor: DeterministicFrameRuntimeDescriptor, count?: number): DeterministicPrototypeRuntimeValidationResult;
+export declare function assertAssetManifestMatches(manifest: DeterministicAssetCookManifest, expected: {
+    readonly engineVersion?: string;
+    readonly assetDbHash?: string;
+}): void;

package/dist/asset-cooking.js

@@ -0,0 +1,364 @@
+import { canonicalStringify, cloneCanonical, defaultChecksum } from './canonical.js';
+import { createDeterministicFrameRuntime } from './engine-runtime.js';
+export function cookDeterministicAssets(source) {
+    validateAssetSource(source);
+    const engineVersion = source.engineVersion ?? 'rdm-assets@1';
+    const dependencies = [...(source.dependencies ?? [])]
+        .map((dependency) => cloneCanonical(dependency))
+        .sort(compareDependencies);
+    const schemaHash = defaultChecksum({
+        kind: 'deterministic-asset-schema',
+        schemaVersion: 1,
+        requiredFields: ['id'],
+        optionalFields: ['type', 'references', 'prototype'],
+        numericPolicy: 'integer-only',
+        dependencyVersionPolicy: 'exact',
+    });
+    const dependencyHash = defaultChecksum(dependencies);
+    const assets = source.assets
+        .map((asset) => cloneCanonical(asset))
+        .sort((left, right) => compareStrings(left.id, right.id));
+    const cookedAssets = assets.map((asset) => {
+        const data = cloneCanonical(asset);
+        return {
+            id: asset.id,
+            type: asset.type ?? 'asset',
+            hash: defaultChecksum({ id: asset.id, data }),
+            data,
+        };
+    });
+    const lookup = Object.fromEntries(cookedAssets.map((asset, index) => [asset.id, index]));
+    const prototypeIds = cookedAssets
+        .filter((asset) => asset.data.prototype === true)
+        .map((asset) => asset.id)
+        .sort(compareStrings);
+    const withoutHash = {
+        schemaVersion: 1,
+        schemaHash,
+        engineVersion,
+        dependencyHash,
+        dependencies,
+        lookupHash: defaultChecksum(lookup),
+        prototypeIds,
+        assetCount: cookedAssets.length,
+        assets: cookedAssets.map((asset) => ({
+            id: asset.id,
+            type: asset.type,
+            hash: asset.hash,
+        })),
+    };
+    const manifest = {
+        ...withoutHash,
+        assetDbHash: defaultChecksum({ engineVersion, schemaHash, dependencyHash, dependencies, cookedAssets }),
+    };
+    const bytes = canonicalStringify({
+        manifest,
+        assets: cookedAssets,
+    });
+    return {
+        manifest,
+        cookedAssets,
+        bytes,
+    };
+}
+export function stableAssetCookJson(result) {
+    return `${canonicalStringify(result)}\n`;
+}
+export function materializePrototypeEntities(cooked, prototypeId, count, options = {}) {
+    if (!Number.isInteger(count) || count < 0) {
+        throw new Error('Prototype count must be a non-negative integer');
+    }
+    const startEntityId = options.startEntityId ?? 1;
+    if (!Number.isInteger(startEntityId) || startEntityId <= 0) {
+        throw new Error('Prototype start entity id must be a positive integer');
+    }
+    const prototype = cooked.cookedAssets.find((asset) => asset.id === prototypeId);
+    if (prototype === undefined) {
+        throw new Error(`Unknown prototype ${prototypeId}`);
+    }
+    if (!cooked.manifest.prototypeIds.includes(prototypeId)) {
+        throw new Error(`Asset ${prototypeId} is not a prototype`);
+    }
+    const components = resolvePrototypeComponents(cooked, prototypeId, new Set());
+    const overrides = options.componentOverrides === undefined
+        ? {}
+        : recordOrThrow(options.componentOverrides, `Prototype ${prototypeId} overrides`);
+    const resolvedComponents = mergeRecords(components, overrides);
+    return Array.from({ length: count }, (_, index) => ({
+        entityId: startEntityId + index,
+        prototypeId,
+        assetDbHash: cooked.manifest.assetDbHash,
+        components: materializeDynamicCollections(resolvedComponents),
+    }));
+}
+export function materializeDeterministicMapEntities(cooked, mapId, options = {}) {
+    const mapAsset = cooked.cookedAssets.find((asset) => asset.id === mapId);
+    if (mapAsset === undefined) {
+        throw new Error(`Unknown map ${mapId}`);
+    }
+    if (mapAsset.type !== 'map') {
+        throw new Error(`Asset ${mapId} is not a map`);
+    }
+    const mapData = recordOrThrow(mapAsset.data, `Map ${mapId}`);
+    const spawns = mapData.spawns;
+    if (!Array.isArray(spawns)) {
+        throw new Error(`Map ${mapId} requires a spawns array`);
+    }
+    const materialized = [];
+    const prototypeIds = [];
+    const usedEntityIds = new Set();
+    let nextEntityId = options.startEntityId ?? 1;
+    for (const [index, spawn] of spawns.entries()) {
+        const spawnRecord = recordOrThrow(spawn, `Map ${mapId}.spawns[${index}]`);
+        const prototypeRef = spawnRecord.prototypeRef;
+        if (typeof prototypeRef !== 'string') {
+            throw new Error(`Map ${mapId}.spawns[${index}].prototypeRef must be a string`);
+        }
+        const count = optionalInteger(spawnRecord.count, `Map ${mapId}.spawns[${index}].count`) ?? 1;
+        if (!Number.isInteger(count) || count < 0) {
+            throw new Error(`Map ${mapId}.spawns[${index}].count must be a non-negative integer`);
+        }
+        const startEntityId = optionalInteger(spawnRecord.startEntityId, `Map ${mapId}.spawns[${index}].startEntityId`) ?? nextEntityId;
+        if (!Number.isInteger(startEntityId) || startEntityId <= 0) {
+            throw new Error(`Map ${mapId}.spawns[${index}].startEntityId must be a positive integer`);
+        }
+        const entities = materializePrototypeEntities(cooked, prototypeRef, count, {
+            startEntityId,
+            componentOverrides: spawnRecord.overrides,
+        });
+        for (const entity of entities) {
+            if (usedEntityIds.has(entity.entityId)) {
+                throw new Error(`Map ${mapId}.spawns[${index}] duplicates entityId ${entity.entityId}`);
+            }
+            usedEntityIds.add(entity.entityId);
+        }
+        materialized.push(...entities);
+        prototypeIds.push(prototypeRef);
+        nextEntityId = Math.max(nextEntityId, startEntityId + count);
+    }
+    const withoutChecksum = {
+        mapId,
+        assetDbHash: cooked.manifest.assetDbHash,
+        mapBakeHash: defaultChecksum({ mapId, assetDbHash: cooked.manifest.assetDbHash, materialized }),
+        spawnCount: spawns.length,
+        materializedEntityCount: materialized.length,
+        prototypeIds: [...new Set(prototypeIds)].sort(compareStrings),
+        materializedEntities: materialized,
+    };
+    return {
+        ...withoutChecksum,
+        checksum: defaultChecksum(withoutChecksum),
+    };
+}
+export function validatePrototypeEntitiesAgainstFrameRuntime(cooked, prototypeId, descriptor, count = 1) {
+    const runtime = createDeterministicFrameRuntime(descriptor, 0);
+    const entities = materializePrototypeEntities(cooked, prototypeId, count);
+    let injectedComponentCount = 0;
+    for (const materialized of entities) {
+        const runtimeEntity = runtime.createEntity();
+        const components = recordOrThrow(materialized.components, `Prototype ${prototypeId} components`);
+        for (const componentId of Object.keys(components).sort(compareStrings)) {
+            const data = recordOrThrow(components[componentId], `Prototype ${prototypeId}.${componentId}`);
+            runtime.setComponent(runtimeEntity, componentId, cloneCanonical(data));
+            injectedComponentCount += 1;
+        }
+    }
+    const snapshot = runtime.snapshot();
+    const result = {
+        prototypeId,
+        materializedEntityCount: entities.length,
+        injectedComponentCount,
+        descriptorComponentCount: descriptor.components.filter((component) => component.singleton !== true).length,
+        runtimeSnapshotChecksum: snapshot.checksum,
+    };
+    return {
+        ...result,
+        checksum: defaultChecksum(result),
+    };
+}
+export function assertAssetManifestMatches(manifest, expected) {
+    if (expected.engineVersion !== undefined && manifest.engineVersion !== expected.engineVersion) {
+        throw new Error(`Stale deterministic asset engine: expected ${expected.engineVersion}, actual ${manifest.engineVersion}`);
+    }
+    if (expected.assetDbHash !== undefined && manifest.assetDbHash !== expected.assetDbHash) {
+        throw new Error(`Stale deterministic asset database hash: expected ${expected.assetDbHash}, actual ${manifest.assetDbHash}`);
+    }
+}
+function validateAssetSource(source) {
+    if (!Array.isArray(source.assets)) {
+        throw new Error('Deterministic asset source requires an assets array');
+    }
+    if (source.schemaVersion !== undefined && source.schemaVersion !== 1) {
+        throw new Error(`Unsupported deterministic asset schema ${source.schemaVersion}`);
+    }
+    validateDependencies(source.dependencies ?? []);
+    const ids = new Set();
+    for (const asset of source.assets) {
+        if (typeof asset.id !== 'string' || asset.id.length === 0) {
+            throw new Error('Every deterministic asset requires a non-empty string id');
+        }
+        if (ids.has(asset.id)) {
+            throw new Error(`Duplicate deterministic asset id ${asset.id}`);
+        }
+        ids.add(asset.id);
+        rejectUnquantizedNumbers(asset, asset.id);
+    }
+    for (const asset of source.assets) {
+        for (const reference of asset.references ?? []) {
+            if (!ids.has(reference)) {
+                throw new Error(`Unresolved deterministic asset reference ${asset.id} -> ${reference}`);
+            }
+        }
+        validateImplicitAssetRefs(asset, ids, asset.id);
+    }
+}
+function validateImplicitAssetRefs(value, ids, path) {
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => validateImplicitAssetRefs(entry, ids, `${path}[${index}]`));
+        return;
+    }
+    if (value === null || typeof value !== 'object') {
+        return;
+    }
+    for (const key of Object.keys(value).sort(compareStrings)) {
+        const entry = value[key];
+        const entryPath = `${path}.${key}`;
+        if (key.endsWith('Ref') && typeof entry === 'string' && !ids.has(entry)) {
+            throw new Error(`Unresolved deterministic asset ref ${entryPath} -> ${entry}`);
+        }
+        if (key.endsWith('Refs') && Array.isArray(entry)) {
+            for (const [index, ref] of entry.entries()) {
+                if (typeof ref === 'string' && !ids.has(ref)) {
+                    throw new Error(`Unresolved deterministic asset ref ${entryPath}[${index}] -> ${ref}`);
+                }
+            }
+        }
+        validateImplicitAssetRefs(entry, ids, entryPath);
+    }
+}
+function recordOrThrow(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
+    }
+    return value;
+}
+function resolvePrototypeComponents(cooked, prototypeId, seen) {
+    if (seen.has(prototypeId)) {
+        throw new Error(`Prototype inheritance cycle at ${prototypeId}`);
+    }
+    seen.add(prototypeId);
+    const prototype = cooked.cookedAssets.find((asset) => asset.id === prototypeId);
+    if (prototype === undefined) {
+        throw new Error(`Unknown prototype ${prototypeId}`);
+    }
+    const data = recordOrThrow(prototype.data, `Prototype ${prototypeId}`);
+    const parentRef = data.extendsRef;
+    const parent = parentRef === undefined
+        ? {}
+        : resolvePrototypeComponents(cooked, stringOrThrow(parentRef, `Prototype ${prototypeId}.extendsRef`), seen);
+    const own = data.components === undefined
+        ? {}
+        : recordOrThrow(data.components, `Prototype ${prototypeId} components`);
+    return mergeRecords(parent, own);
+}
+function mergeRecords(base, override) {
+    const merged = {};
+    for (const key of [...new Set([...stableRecordKeys(base), ...stableRecordKeys(override)])].sort(compareStrings)) {
+        const baseValue = base[key];
+        const overrideValue = override[key];
+        if (overrideValue === undefined) {
+            merged[key] = cloneCanonical(baseValue);
+        }
+        else if (isPlainRecord(baseValue) && isPlainRecord(overrideValue) && !isCollectionDescriptor(overrideValue)) {
+            merged[key] = mergeRecords(baseValue, overrideValue);
+        }
+        else {
+            merged[key] = cloneCanonical(overrideValue);
+        }
+    }
+    return merged;
+}
+function materializeDynamicCollections(value) {
+    if (Array.isArray(value)) {
+        return value.map(materializeDynamicCollections);
+    }
+    if (!isPlainRecord(value)) {
+        return cloneCanonical(value);
+    }
+    if (isCollectionDescriptor(value)) {
+        const kind = stringOrThrow(value.collection, 'collection');
+        if (kind === 'list' || kind === 'buffer') {
+            const values = Array.isArray(value.values) ? value.values : [];
+            return values.map(materializeDynamicCollections);
+        }
+        if (kind === 'set') {
+            const values = Array.isArray(value.values) ? value.values : [];
+            return [...new Set(values.map((entry) => canonicalStringify(materializeDynamicCollections(entry))))]
+                .sort(compareStrings)
+                .map((entry) => JSON.parse(entry));
+        }
+        if (kind === 'map' || kind === 'dictionary') {
+            const entries = recordOrThrow(value.entries ?? {}, `${kind} entries`);
+            return Object.fromEntries(Object.keys(entries).sort(compareStrings).map((key) => [key, materializeDynamicCollections(entries[key])]));
+        }
+        throw new Error(`Unsupported deterministic prototype collection ${kind}`);
+    }
+    return Object.fromEntries(Object.keys(value).sort(compareStrings).map((key) => [key, materializeDynamicCollections(value[key])]));
+}
+function isCollectionDescriptor(value) {
+    return typeof value.collection === 'string';
+}
+function isPlainRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function stringOrThrow(value, label) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+    return value;
+}
+function optionalInteger(value, label) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Number.isInteger(value)) {
+        throw new Error(`${label} must be an integer`);
+    }
+    return value;
+}
+function stableRecordKeys(record) {
+    return Reflect.ownKeys(record)
+        .filter((key) => typeof key === 'string')
+        .sort(compareStrings);
+}
+function validateDependencies(dependencies) {
+    for (const dependency of dependencies) {
+        if (/[\^~*xX]/.test(dependency.version) || dependency.version === 'latest') {
+            throw new Error(`Nondeterministic dependency version ${dependency.name}@${dependency.version}`);
+        }
+    }
+}
+function compareDependencies(left, right) {
+    return compareStrings(left.name, right.name) || compareStrings(left.version, right.version);
+}
+function rejectUnquantizedNumbers(value, path) {
+    if (typeof value === 'number') {
+        if (!Number.isInteger(value)) {
+            throw new Error(`Unquantized float at ${path}`);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => rejectUnquantizedNumbers(entry, `${path}[${index}]`));
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        for (const key of Object.keys(value).sort(compareStrings)) {
+            const entry = value[key];
+            rejectUnquantizedNumbers(entry, `${path}.${key}`);
+        }
+    }
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/authority-room.d.ts

@@ -0,0 +1,217 @@
+import { type ConfirmedInputFrame, type EncodedInput } from './input-authority.js';
+import type { SyncplayMatchLog } from './match-log.js';
+/**
+ * Transport-agnostic, game-agnostic deterministic authority room (§6 M2).
+ *
+ * This is the reusable core a host (mp-room-server's worker) wraps: it assigns slots, owns and
+ * distributes the RNG seed, orders/confirms inputs via {@link createInputAuthority} (running NO
+ * simulation), and broadcasts confirmed-input frames on a server tick. Every deterministic game
+ * uses this one component — there is no per-game server code. The host supplies only a transport
+ * (broadcast/sendTo) and drives the tick.
+ *
+ * It speaks the frozen `rdm-local-authority/v1` session protocol (`session-wire.ts`): players are
+ * greeted with `session-start`, send `input`, and receive `confirmed-input`.
+ */
+export interface AuthorityRoomTransport {
+    broadcast(msgType: string, payload: string): void;
+    sendTo(playerId: string, msgType: string, payload: string): void;
+}
+export interface DeterministicAuthorityRoomConfig {
+    readonly playerCount: number;
+    readonly seed: number;
+    readonly hardToleranceTicks: number;
+    readonly tickRateHz: number;
+    readonly redundancyWindowTicks: number;
+    /**
+     * The game's canonical "no-op" input, used when a slot's real input never arrives and there is
+     * no prior confirmed input to repeat. Game-defined (the authority never interprets it), so it
+     * MUST be supplied — the room is game-agnostic and cannot assume an input shape.
+     */
+    readonly neutralInput: EncodedInput;
+    /** Reject inputs further ahead than `confirmedThrough + maxFutureTicks` (bounds buffering). Default 256. */
+    readonly maxFutureTicks?: number;
+    /**
+     * Hold the authority clock until EVERY slot has joined (lobby-style
+     * synchronized start). Default false: the clock runs from the first join and
+     * later players catch up via input-history replay (drop-in). Games that want
+     * a hard "everyone starts together" opt in.
+     */
+    readonly waitForFullRoom?: boolean;
+    /**
+     * How many confirmed frames to retain for late-join/rejoin catch-up.
+     * A joiner must replay the input history from tick 0 to reconstruct state
+     * deterministically (the authority never runs the sim, so history IS the
+     * state). Joins after tick 0 has been pruned are rejected with
+     * 'history-unavailable' — fail loud, never desync. Frames are tiny (encoded
+     * inputs), so the default retains a full hour at 60 Hz for a few MB.
+     * Default 216_000.
+     */
+    readonly historyRetentionTicks?: number;
+    /**
+     * Desync telemetry (§3): invoked when two clients report different state checksums for the same
+     * tick. Detection ONLY — the match is never halted (checksum cheat-gating is deliberately avoided).
+     */
+    readonly onDesync?: (info: AuthorityRoomDesyncInfo) => void;
+    /** msgType used for session-start / confirmed-input broadcasts (host wire envelope). Default 'rdm'. */
+    readonly sessionMsgType?: string;
+    /**
+     * How often (in authority ticks) to acquire a validated client-donated state
+     * snapshot (M5.5). Once one is stored, history below its tail is pruned and
+     * late joins are served snapshot + input tail regardless of match age.
+     * Default 3600 (1 min @ 60 Hz).
+     */
+    readonly snapshotCadenceTicks?: number;
+    /** Abandon a donor transfer that has not completed after this many ticks. Default 600. */
+    readonly transferTimeoutTicks?: number;
+    /** Snapshot acquisition telemetry: stored snapshots and rejected/abandoned transfers. */
+    readonly onSnapshotEvent?: (event: AuthorityRoomSnapshotEvent) => void;
+    /**
+     * Keep the confirmed-input history back to tick 0 even after a validated
+     * snapshot is stored (G3 — replay-verified matches). Normally the snapshot
+     * prunes everything below it; with full history the room can export a
+     * complete server-ordered match log (`matchLog()`) that an offline verifier
+     * re-simulates for score verification. Memory cost is bounded by
+     * `historyRetentionTicks` — a match longer than that loses tick 0 and stops
+     * being log-verifiable (matchLog() returns undefined; fail loud, never lie).
+     */
+    readonly preserveFullHistory?: boolean;
+    /**
+     * Catch-up telemetry (M8): fired whenever the room serves a player state
+     * reconstruction — late join, rejoin, reconnect refill, or post-restore
+     * resync — with which plan ran and how much tail was replayed.
+     */
+    readonly onCatchUpEvent?: (event: AuthorityRoomCatchUpEvent) => void;
+    /**
+     * Rebuild a crashed room from its persisted record (M6.5): frontier, rejoin
+     * map, seated players, the input tail, and the latest validated snapshot.
+     * Construction is fail-loud on any inconsistency — a silently-empty restore
+     * would strand every surviving client. After building the room the host
+     * MUST call `resyncSeatedPlayers()` so surviving clients re-seat.
+     */
+    readonly restoreFrom?: DeterministicAuthorityRoomRestoreState;
+}
+export interface DeterministicAuthorityRoomRestoreState {
+    readonly now: number;
+    readonly confirmedThrough: number;
+    readonly everSlots: Readonly<Record<string, number>>;
+    readonly seatedPlayers: readonly string[];
+    readonly tail: readonly ConfirmedInputFrame[];
+    readonly snapshotBytes?: string;
+    readonly schemaHash?: string;
+}
+export interface AuthorityRoomCatchUpEvent {
+    readonly playerId: string;
+    readonly kind: 'join' | 'rejoin' | 'reconnect' | 'resync';
+    readonly plan: 'snapshot' | 'history';
+    /** Confirmed frames sent for replay (frontier - tail start + 1). */
+    readonly tailFrames: number;
+    readonly snapshotTick?: number;
+}
+export interface AuthorityRoomSnapshotEvent {
+    readonly kind: 'stored' | 'rejected';
+    readonly donorId?: string;
+    readonly tick?: number;
+    readonly reason?: string;
+}
+export interface AuthorityRoomDesyncInfo {
+    readonly tick: number;
+    readonly slot: number;
+    readonly checksum: string;
+    readonly conflictingSlot: number;
+    readonly conflictingChecksum: string;
+    /**
+     * Every checksum reported for this tick so far (including the report that
+     * triggered detection), by slot. Lets the host pick the MINORITY client to
+     * resync instead of guessing between the two conflicting slots.
+     */
+    readonly reportsAtTick: Readonly<Record<number, string>>;
+}
+/** Latest client-reported netcode telemetry, by slot (G8). */
+export interface AuthorityRoomClientNetStats {
+    readonly tick: number;
+    readonly rttMs: number;
+    readonly rollbacks: number;
+    readonly maxRollbackDepth: number;
+    readonly timescalePermille: number;
+    readonly inputDelayTicks: number;
+}
+export interface AuthorityRoomNetcodeStats {
+    readonly confirmedThrough: number;
+    /** Ticks in which each slot's input had to be substituted (cumulative). */
+    readonly substitutedTicksBySlot: Readonly<Record<number, number>>;
+    readonly clientStats: Readonly<Record<number, AuthorityRoomClientNetStats>>;
+}
+export interface AuthorityRoomJoinResult {
+    readonly accepted: boolean;
+    readonly slot?: number;
+    readonly reason?: 'room-full' | 'already-joined' | 'history-unavailable';
+    /** True when this join re-attached a previously-seen playerId to its original slot. */
+    readonly rejoined?: boolean;
+}
+export interface AuthorityRoomSnapshot {
+    readonly confirmedThrough: number;
+    readonly now: number;
+    readonly slots: Readonly<Record<string, number>>;
+    /** Every playerId ever seated, by slot — the rejoin reclaim map. */
+    readonly everSlots: Readonly<Record<string, number>>;
+    /** Lowest confirmed tick still retained (-1 when nothing is confirmed). */
+    readonly earliestRetainedTick: number;
+    /**
+     * Metadata of the latest VALIDATED state snapshot. The raw bytes are
+     * deliberately excluded — hosts persist this record (mp-room-server hard-caps
+     * persisted state at 1 MB) — and exposed via `latestSnapshotBytes()` for
+     * out-of-band persistence (M6.5).
+     */
+    readonly latestSnapshot?: AuthorityRoomStoredSnapshotMeta;
+}
+export interface AuthorityRoomStoredSnapshotMeta {
+    readonly tick: number;
+    readonly snapshotChecksum: string;
+    readonly descriptorHash: string;
+    readonly schemaHash?: string;
+    readonly byteLength: number;
+}
+export interface DeterministicAuthorityRoom {
+    readonly confirmedThrough: number;
+    readonly playerCount: number;
+    onPlayerJoin(playerId: string): AuthorityRoomJoinResult;
+    /** Seat a read-only spectator (G11): role 'spectator', no slot, full catch-up + live follow. */
+    onSpectatorJoin(playerId: string): boolean;
+    onPlayerMessage(playerId: string, envelope: string): void;
+    onPlayerLeave(playerId: string): void;
+    /**
+     * A player's transport re-attached inside the host's grace window (socket
+     * swap; no leave/join fired). Re-unicasts the confirmed-input history so any
+     * frames missed while offline are refilled — clients dedupe already-applied
+     * ticks, so this is idempotent.
+     */
+    onPlayerReconnected(playerId: string): void;
+    /** Advance the authority by one server tick and broadcast newly-confirmed frames. */
+    onTick(): void;
+    snapshot(): AuthorityRoomSnapshot;
+    /** Raw bytes of the latest validated state snapshot (see AuthorityRoomSnapshot.latestSnapshot). */
+    latestSnapshotBytes(): string | undefined;
+    /** The retained confirmed-input tail (earliest retained .. frontier), for persistence (M6.5). */
+    confirmedTail(): readonly ConfirmedInputFrame[];
+    /** After a restore: re-greet every seated player (session-start + snapshot + tail). */
+    resyncSeatedPlayers(): void;
+    /**
+     * Force one seated player through the full reset + re-hydrate path
+     * (session-start re-greet + snapshot/history catch-up) — the live-desync
+     * response (G4): the minority client of a checksum conflict is re-seated from
+     * the validated snapshot exactly like a late joiner instead of drifting for
+     * the rest of the match. Returns false when the player is not seated or no
+     * catch-up plan exists (nothing was sent).
+     */
+    resyncPlayer(playerId: string): boolean;
+    /** Cumulative substitution counters + latest per-client telemetry (G8). */
+    netcodeStats(): AuthorityRoomNetcodeStats;
+    /**
+     * The complete server-ordered match log (G3): every confirmed input frame
+     * from tick 0, plus the descriptor a verifier needs to re-simulate. Returns
+     * undefined when history no longer reaches tick 0 (snapshot-pruned without
+     * `preserveFullHistory`, or the match outlived `historyRetentionTicks`).
+     */
+    matchLog(): SyncplayMatchLog | undefined;
+}
+export declare function createDeterministicAuthorityRoom(transport: AuthorityRoomTransport, config: DeterministicAuthorityRoomConfig): DeterministicAuthorityRoom;