@voltro/plugin-rooms 0.0.0-stage → 0.87.0

package/dist/lockstep.d.ts

@@ -0,0 +1,436 @@
+import { Schema } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+/* Excluded from this release type: captureLockstepClientOptions */
+
+/* Excluded from this release type: captureLockstepClientPolicy */
+
+export declare const createLockstepClientSimulation: <S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>>(simulation: Simulation<S, I, O>, seed: number, options: O["Type"], client: LockstepClientOptions<I["Type"]>) => LockstepClientSimulation<S, I, O>;
+
+export declare const createLockstepPolicies: (options?: LockstepPolicyOptions, strategies?: LockstepPolicyStrategies) => LockstepPolicyOwner;
+
+export declare const createRoomLockstepClientSession: <S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>>(transport: RoomTransport, simulation: Simulation<S, I, O>, manifest: RoomWireManifest<S, I>, options: RoomLockstepClientSessionOptions<I["Type"]>) => RoomLockstepClientSession<S, I, O>;
+
+export declare const isRoomLockstepClientSession: (value: unknown) => value is RoomLockstepClientSession<Schema.Codec<unknown, unknown>, Schema.Codec<unknown, unknown>, Schema.Codec<unknown, unknown>>;
+
+export declare type LockstepAdvance<S> = {
+    readonly _tag: 'advanced';
+    readonly snapshot: SimulationSnapshot<S>;
+    readonly predictedPlayers: ReadonlyArray<number>;
+} | {
+    readonly _tag: 'stalled';
+    readonly tick: number;
+    readonly reason: 'inputs' | 'horizon';
+    readonly missingTick: number;
+    readonly waitingFor: ReadonlyArray<number>;
+};
+
+export declare interface LockstepClientMetrics {
+    readonly rollbackReplays: number;
+    readonly rollbackSteps: number;
+    readonly stallAttempts: number;
+}
+
+export declare interface LockstepClientOptions<I> {
+    readonly localPlayerId: number;
+    /** Optional actual complete starting matrix; absent waits for server tick1. */
+    readonly initialInputs?: ReadonlyArray<SimulationPlayerInput<I>>;
+    /** Complete admitted roster when no starting intention matrix is supplied. */
+    readonly playerIds?: ReadonlyArray<number>;
+    readonly inputDelayTicks?: number;
+    readonly rollbackHorizonTicks?: number;
+    readonly maxFutureTicks?: number;
+    readonly maxPlayers?: number;
+    readonly maxRejectionAttempts?: number;
+    readonly inputPrediction?: LockstepInputPrediction<I>;
+    /** The local player joins a running match: it is not in `playerIds` yet and enters the
+     * roster through `join` at the tick the server announces. */
+    readonly lateJoin?: boolean;
+}
+
+/** Local simulation composition only. Call confirm exclusively with a complete
+ * matrix ordered/admitted by the actual Room server. This class has no socket,
+ * Subject, SQL, store, transport, clock, timer or automatic authority grant. */
+export declare class LockstepClientSimulation<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    #private;
+    constructor(simulation: Simulation<S, I, O>, seed: number, options: (O)["Type"], offered: LockstepClientOptions<(I)["Type"]>);
+    get tick(): number;
+    get confirmedThroughTick(): number;
+    get metrics(): LockstepClientMetrics;
+    snapshot(): SimulationSnapshot<(S)["Type"]>;
+    /** A hash carrier may use only a genuinely confirmed, already executed tick. */
+    confirmedSnapshot(tick: number): SimulationSnapshot<(S)["Type"]>;
+    /** Local reset seam. Network owner must establish reliable server/epoch/Session
+     * provenance. A complete retained or explicitly server-supplied input base is mandatory. */
+    installServerSnapshot(offered: SimulationSnapshot<(S)["Type"]>, suppliedInputs?: ReadonlyArray<SimulationPlayerInput<(I)["Type"]>>, suppliedContinuation?: ReadonlyArray<SimulationTickInputs<(I)["Type"]>>): SimulationSnapshot<(S)["Type"]>;
+    /** Pure local seam after the network owner proves current server provenance.
+     * Seeded history holds actual matrices; normal advance runs one author tick. */
+    installConfirmedHistory(offered: SimulationInputHistory<(I)["Type"]>, limits?: SimulationInputHistoryCodecOptions): number;
+    private work;
+    private captureMatrix;
+    /** The roster a tick's matrix covers: the Start roster plus joins effective by then, in ID order. */
+    private rosterAt;
+    private completeMatrix;
+    /** Late join: `playerId` plays from `tick` on, which must still be ahead of the confirmed
+     * frontier. Earlier predictions without it roll back when the widened matrix arrives. */
+    join(tick: number, playerId: number): void;
+    private matrix;
+    private prune;
+    submitLocal(input: (I)["Type"]): LockstepLocalInput<(I)["Type"]>;
+    /** Last authored local tick inputs for a future wire redundancy carrier. */
+    recentLocalInputs(count?: number): ReadonlyArray<LockstepLocalInput<(I)["Type"]>>;
+    advance(): LockstepAdvance<(S)["Type"]>;
+    /** Local caller must verify actual server/Room provenance first. Conflicting
+     * already admitted matrices refuse; matching hashes never decide equality. */
+    confirm(tick: number, offered: ReadonlyArray<SimulationPlayerInput<(I)["Type"]>>): LockstepConfirmation;
+}
+
+export declare type LockstepConfirmation = {
+    readonly _tag: 'queued' | 'matched' | 'duplicate';
+    readonly tick: number;
+} | {
+    readonly _tag: 'replayed';
+    readonly tick: number;
+    readonly steps: number;
+} | {
+    readonly _tag: 'expired';
+    readonly tick: number;
+    readonly oldestTick: number;
+};
+
+export declare type LockstepDesyncAction = 'resync' | 'end' | 'flag';
+
+export declare interface LockstepDesyncContext {
+    readonly tick: number;
+    readonly playerId: number;
+    readonly expected: Uint64Words;
+    readonly received: Uint64Words;
+}
+
+export declare type LockstepInputPrediction<I> = 'repeat-last' | 'none' | ((last: I, context: {
+    readonly playerId: number;
+    readonly tick: number;
+}) => I);
+
+export declare interface LockstepLocalInput<I> {
+    readonly tick: number;
+    readonly input: I;
+}
+
+export declare interface LockstepPolicyOptions {
+    readonly refereeLagTicks?: number;
+    readonly stallPolicy?: LockstepStallPolicyOptions;
+    readonly onDesync?: LockstepDesyncAction;
+}
+
+/** Shared actual pure policy consumer for local simulation/server role ownership.
+ * Drop-player is an explicit host decision, never synthetic transport closure. */
+export declare class LockstepPolicyOwner {
+    #private;
+    readonly refereeLagTicks: number;
+    readonly stallPolicy: LockstepStallPolicy;
+    constructor(offered?: LockstepPolicyOptions, overrides?: LockstepPolicyStrategies);
+    stallDecision(tick: number, elapsedTicks: number, offeredMask: Uint64Words): LockstepStallDecision;
+    desync(offered: LockstepDesyncContext): LockstepDesyncAction;
+}
+
+export declare interface LockstepPolicyStrategies {
+    readonly refereeLag?: (configuredTicks: number) => number;
+    readonly stallPolicy?: (options: LockstepStallPolicyOptions) => LockstepStallPolicy;
+    readonly onDesync?: (incident: LockstepDesyncContext, configuredAction: LockstepDesyncAction) => LockstepDesyncAction;
+}
+
+export declare type LockstepStallDecision = {
+    readonly _tag: 'waiting';
+    readonly tick: number;
+    readonly elapsedTicks: number;
+    readonly waitingFor: Uint64Words;
+} | {
+    readonly _tag: 'action';
+    readonly tick: number;
+    readonly elapsedTicks: number;
+    readonly waitingFor: Uint64Words;
+    readonly action: 'pause' | 'drop-player';
+};
+
+export declare interface LockstepStallPolicy {
+    readonly afterTicks: number;
+    readonly action: 'pause' | 'drop-player';
+}
+
+export declare interface LockstepStallPolicyOptions {
+    readonly afterTicks?: number;
+    readonly action?: 'pause' | 'drop-player';
+}
+
+/** PCG-XSH-RR 64/32. Numeric seeds are unsigned 32-bit; word seeds retain 64 bits.
+ * Algorithm reference: https://www.pcg-random.org/using-pcg-c-basic.html
+ * No global generator, BigInt, native dependency or implicit time/entropy seed. */
+declare class Pcg32 {
+    #private;
+    constructor(seed: Pcg32Seed, stream?: Pcg32Seed, maxRejectionAttempts?: number);
+    get maxRejectionAttempts(): number;
+    nextU32(): number;
+    /** Rejection removes modulo bias. Exhaustion consumes exactly the bounded
+     * draws and fails; it never returns a biased fallback or substitutes entropy. */
+    bounded(bound: number): number;
+    snapshot(): Pcg32Snapshot;
+    restore(offered: Pcg32Snapshot): void;
+    clone(): Pcg32;
+    /** Exact skip-ahead modulo 2^64; at most 32 iterations for this delta API. */
+    advance(delta: number): void;
+}
+
+declare type Pcg32Seed = number | Uint64Words;
+
+declare interface Pcg32Snapshot {
+    readonly stateHi: number;
+    readonly stateLo: number;
+    readonly incrementHi: number;
+    readonly incrementLo: number;
+}
+
+declare class ProtocolError extends ProtocolError_base {
+    get message(): string;
+}
+
+declare const ProtocolError_base: Schema.Class<ProtocolError, Schema.TaggedStruct<"ProtocolError", {
+    readonly detail: Schema.String;
+}>, YieldableError>;
+
+/** Actual default prediction. Caller supplies bounded captured input and owns
+ * copy/authority; returning the last value does not confirm a server tick. */
+export declare const repeatLastLockstepInput: <I>(last: I, _context: {
+    readonly playerId: number;
+    readonly tick: number;
+}) => I;
+
+/** Every option present and defined: `Required` keeps an explicit `| undefined`, this removes it. */
+declare type Resolved<T> = {
+    readonly [K in keyof T]-?: Exclude<T[K], undefined>;
+};
+
+declare interface RoomChannel {
+    readonly schema: Schema.Codec<unknown, unknown>;
+    readonly direction: 'both' | 'server' | 'client';
+    readonly reliable: boolean;
+}
+
+declare interface RoomCodecLimits {
+    readonly maxBytes: number;
+    readonly maxCollectionLength: number;
+    readonly maxFieldId: number;
+}
+
+declare interface RoomDatagramLane {
+    readonly maxDatagramBytes: number;
+    send(frame: Uint8Array): void;
+    onFrame(listener: (frame: Uint8Array, receivedAt: number) => void): () => void;
+}
+
+export declare interface RoomLockstepClientObservation<S> {
+    readonly status: RoomLockstepClientSessionStatus;
+    readonly sessionId: string | null;
+    readonly epoch: number | null;
+    readonly localPlayerId: number | null;
+    readonly roster: ReadonlyArray<RoomLockstepClientRosterPlayer> | null;
+    readonly snapshot: SimulationSnapshot<S> | null;
+    readonly metrics: ReturnType<RoomLockstepClientSession<Schema.Codec<unknown, unknown>, Schema.Codec<unknown, unknown>, Schema.Codec<unknown, unknown>>['metrics']>;
+}
+
+export declare type RoomLockstepClientRosterPlayer = RoomLockstepWirePlayer;
+
+/** Browser-safe network owner over the current Room codec/transport and actual
+ * pure rollback consumer. Reliable host mapping precedes all author initialization.
+ * No SQL/Store/secret/timer or client state-submit capability is acquired. */
+export declare class RoomLockstepClientSession<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    #private;
+    constructor(transport: RoomTransport, simulation: Simulation<S, I, O>, manifest: RoomWireManifest<S, I>, offered: RoomLockstepClientSessionOptions<(I)["Type"]>);
+    private work;
+    private live;
+    private current;
+    private notify;
+    subscribe(listener: () => void): () => void;
+    onMessage(channelName: string, listener: (payload: unknown) => void): () => void;
+    get status(): RoomLockstepClientSessionStatus;
+    get failure(): ProtocolError | null;
+    get id(): string | null;
+    get epoch(): number | null;
+    roster(): ReadonlyArray<RoomLockstepClientRosterPlayer> | null;
+    /** Start roster plus joins effective by `tick`, in slot order (the wire matrix order). */
+    private rosterAt;
+    get localPlayerId(): number | null;
+    snapshot(): SimulationSnapshot<S["Type"]> | null;
+    /** Stable read identity between actual notifications, suitable for React's
+     * external-store contract. Owns no timer or native connection. */
+    observation(): RoomLockstepClientObservation<(S)["Type"]>;
+    metrics(): Readonly<{
+        status: RoomLockstepClientSessionStatus;
+        tick: number | null;
+        confirmedThroughTick: number | null;
+        catchUpTicks: number;
+        pendingWrites: number;
+        pendingIntent: boolean;
+        retainedLocalInputs: number;
+        retainedHashClaims: number;
+        stalls: number;
+        resyncs: number;
+        hashFlags: number;
+        waitingFor: Uint64Words | null;
+        observerErrors: number;
+        rollbackReplays: number;
+        rollbackSteps: number;
+    }>;
+    private encode;
+    private write;
+    start(token: Uint8Array): Promise<void>;
+    /** The existing Room message wire is separate from authoritative intentions. */
+    message(channelName: string, payload: unknown): Promise<void>;
+    private receive;
+    private prune;
+    advance(): LockstepAdvance<(S)["Type"]>;
+    sendIntent(input: (I)["Type"]): Promise<void>;
+    private deliverIntent;
+    /** A reliable write handed to the transport now, in order; `accepted` when the transport took it. */
+    private handOff;
+    sendInitialIntents(input?: (I)["Type"]): Promise<void>;
+    resendRetainedIntent(): Promise<void>;
+    retryIntent(): Promise<void>;
+    sendHash(tick: number): Promise<void>;
+    private release;
+    close(): void;
+    closeAsync(): Promise<void>;
+    settled(): Promise<void>;
+}
+
+export declare interface RoomLockstepClientSessionOptions<I> extends Omit<LockstepClientOptions<I>, 'playerIds' | 'localPlayerId'> {
+    /** Optional expected identity; actual admission always comes from reliable LsStart. */
+    readonly localPlayerId?: number;
+    readonly roster?: ReadonlyArray<RoomLockstepClientRosterPlayer>;
+    readonly redundantInputs?: number;
+    readonly hashEvery?: number;
+    /** Retains actual immutable claim provenance independently of rollback state. */
+    readonly hashHistoryTicks?: number;
+    readonly maxPendingWrites?: number | undefined;
+    readonly maxFrameBytes?: number;
+    /** Work budget for reliable actual input-history bootstrap, not a load claim. */
+    readonly maxBootstrapTicks?: number;
+}
+
+export declare type RoomLockstepClientSessionStatus = 'connecting' | 'waitingStart' | 'joined' | 'stalled' | 'left' | 'kicked' | 'faulted';
+
+/** Public opaque simulation identities, never Subjects or Session credentials. */
+declare interface RoomLockstepWirePlayer {
+    readonly slot: number;
+    readonly playerId: number;
+}
+
+declare interface RoomReliableLane {
+    send(frame: Uint8Array): Promise<void>;
+    onFrame(listener: (frame: Uint8Array, receivedAt: number) => void): () => void;
+}
+
+/** Plain mutable state; the author receives no store or database capability. */
+declare type RoomState<A> = A extends ReadonlyArray<infer V> ? Array<RoomState<V>> : A extends object ? {
+    -readonly [K in keyof A]: RoomState<A[K]>;
+} : A;
+
+declare interface RoomTransport {
+    readonly name: 'ws' | 'wt';
+    readonly reliable: RoomReliableLane;
+    readonly unreliable?: RoomDatagramLane | undefined;
+    readonly signal: AbortSignal;
+    stats(): {
+        readonly rttMs: number | null;
+        readonly queuedBytes: number;
+        readonly droppedDatagrams: number;
+    };
+    close(code: number, reason: string): void;
+    /** When provided, joins actual parent/stream withdrawal and permits retry.
+     * Synchronous close alone does not establish native terminal evidence. */
+    closeAsync?(code: number, reason: string): Promise<void>;
+}
+
+declare interface RoomWireManifest<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>> {
+    readonly state: S;
+    readonly input: I;
+    readonly messages?: Readonly<Record<string, RoomChannel>>;
+}
+
+/** Exported default hash slot, reusing the admitted schema state codec. */
+export declare const schemaSimulationHash: <S extends Schema.Codec<unknown, unknown>>(codec: SimulationStateCodec<S>, state: S["Type"]) => Uint64Words;
+
+declare interface Simulation<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    readonly definition: SimulationDefinition<S, I, O>;
+    readonly stateCodec: SimulationStateCodec<S>;
+    readonly inputCodec: SimulationStateCodec<I>;
+    readonly optionsCodec: SimulationStateCodec<O>;
+}
+
+declare interface SimulationDefinition<S extends Schema.Codec<unknown, unknown>, I extends Schema.Codec<unknown, unknown>, O extends Schema.Codec<unknown, unknown>> {
+    readonly state: S;
+    readonly input: I;
+    readonly options: O;
+    readonly init: (seed: number, options: (O)["Type"]) => (S)["Type"];
+    readonly step: (state: RoomState<(S)["Type"]>, inputs: ReadonlyArray<SimulationPlayerInput<(I)["Type"]>>, tick: number, rng: Pcg32) => (S)["Type"];
+    readonly hash?: (state: (S)["Type"]) => Uint64Words;
+    /** Late join: runs before `step` at the tick a player's input first appears (it was absent
+     * from the previous tick's inputs), in player-ID order, e.g. to spawn the player. Pure and
+     * deterministic like `step`. Start players are `init`'s job: tick 1 runs no join. */
+    readonly join?: (state: RoomState<(S)["Type"]>, playerId: number, tick: number, rng: Pcg32) => (S)["Type"];
+    readonly limits?: Partial<SimulationValueLimits>;
+}
+
+declare interface SimulationInputHistory<I> {
+    readonly fromTick: number;
+    readonly playerIds: ReadonlyArray<number>;
+    readonly inputs: ReadonlyArray<SimulationTickInputs<I>>;
+    /** Late joins (LSI/v2): these `playerIds` appear in rows from `tick` on. */
+    readonly joins?: ReadonlyArray<{
+        readonly playerId: number;
+        readonly tick: number;
+    }>;
+}
+
+declare interface SimulationInputHistoryCodecOptions {
+    readonly maxBytes?: number | undefined;
+    readonly maxPlayers?: number;
+    readonly maxTicks?: number;
+}
+
+declare interface SimulationPlayerInput<I> {
+    readonly playerId: number;
+    readonly input: I;
+}
+
+declare interface SimulationSnapshot<S> {
+    readonly tick: number;
+    readonly state: S;
+    readonly rng: Pcg32Snapshot;
+    readonly hash: Uint64Words;
+}
+
+declare interface SimulationStateCodec<S extends Schema.Codec<unknown, unknown>> {
+    readonly limits: SimulationValueLimits;
+    /** Admitted capture/hash plan, not a binary Room wire schema. */
+    schemaDescription?(): string;
+    capture(value: unknown): (S)["Type"];
+    hash(value: (S)["Type"]): Uint64Words;
+}
+
+declare interface SimulationTickInputs<I> {
+    readonly tick: number;
+    readonly inputs: ReadonlyArray<SimulationPlayerInput<I>>;
+}
+
+declare interface SimulationValueLimits extends RoomCodecLimits {
+    readonly maxNodes: number;
+}
+
+/** Exact unsigned 64-bit integer as independent 32-bit words. */
+declare interface Uint64Words {
+    readonly hi: number;
+    readonly lo: number;
+}
+
+export { }