@joystyk/rooms 0.0.0 → 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,374 @@
+import type { AnyDiscreteEngine, EngineInput, Json, JobOutcome, JobRequest, Outcome, Result, Rng, RngState, SeatId, SeatInfo } from '@joystyk/contracts';
+import type { ActionId, BankSetting, GamePin, OfferKind, RoomCode, RoomControl, RoomPhase, ServerMessage, WelcomeMessage } from './protocol/index.js';
+export type { ActionId, BankSetting, GamePin, OfferKind, RoomCode, RoomControl, RoomOffer, RoomPhase, } from './protocol/index.js';
+/** Assigned by the adapter to each socket; never persisted. */
+export type ConnId = string;
+/** Per-game defaults come from the manifest; the creator may change some within bounds. */
+export type RoomPolicy = {
+    readonly seats: {
+        readonly min: number;
+        readonly max: number;
+    };
+    /** 'host': a lobby, then the host starts. 'immediate': the match starts at creation with AI in every other seat. */
+    readonly start: 'host' | 'immediate';
+    /** Someone arriving mid-match watches, or takes over an unclaimed AI seat. */
+    readonly lateJoin: 'spectate' | 'take-ai-seat';
+    /** After the grace period, an absent player's seat goes to the AI, has its turns expired, or waits. */
+    readonly absent: 'ai' | 'timeout' | 'wait';
+    readonly graceMs: number;
+    /** Per-move clock; null = off, or a bank runs instead. */
+    readonly decisionMs: number | null;
+    /** A time bank with increment (the manifest's `clock.mode: 'bank'`); when set, decisionMs is null. */
+    readonly bank?: BankSetting | null;
+    /** 0 disables watching. */
+    readonly maxSpectators: number;
+    /** Delete after this long without a change. */
+    readonly retainMs: number;
+};
+export type SeatClaim = {
+    readonly tokenHash: string;
+    readonly name: string;
+};
+export type SeatRecord = {
+    readonly id: SeatId;
+    /** Who holds the seat. Null: open, or played by the AI with nobody to give it back to. */
+    readonly claim: SeatClaim | null;
+    readonly controller: 'human' | 'ai';
+    readonly aiLevel: string | null;
+    readonly ready: boolean;
+};
+export type DecisionClock = {
+    readonly seat: SeatId;
+    /** Epoch ms. */
+    readonly at: number;
+    /** The clock belongs to this decision: it survives changes that leave the seat's decision alone. */
+    readonly decisionRevision: number;
+    /** Bank mode: when the bank starts running (after the playback hold). */
+    readonly startsAt?: number;
+    /** Bank mode: false when the engine's `decisionMs` replaced the bank for this decision. */
+    readonly onBank?: boolean;
+};
+export type PendingJob = {
+    /** Id, kind and payload, from the contract. */
+    readonly request: JobRequest;
+    /** The revision that requested it. */
+    readonly revision: number;
+};
+export type MatchRecord = {
+    /** 1, then +1 per rematch. */
+    readonly number: number;
+    /** Pinned for this match. */
+    readonly game: GamePin;
+    readonly config: Json;
+    /** The seats `init` received: with `seed`, `config` and the input log, the replay. */
+    readonly seats: readonly SeatInfo[];
+    /** The engine rng at init: the replay seed. */
+    readonly seed: RngState;
+    /** Engine state. */
+    readonly state: Json;
+    /** Never sent to a client. */
+    readonly rng: RngState;
+    /**
+     * The AI's stream, kept apart so AI choices never shift the engine's draws. Each decision
+     * forks a child from it; it moves on only when an AI move is accepted (rule 7).
+     */
+    readonly aiRng: RngState;
+    /** Per seat: the last revision that changed its `decisionKey`. */
+    readonly decisionRevision: readonly number[];
+    /** Durable: they survive a restart. */
+    readonly clocks: readonly DecisionClock[];
+    /** Bank mode: each seat's remaining bank in milliseconds. */
+    readonly banks?: readonly number[];
+    readonly jobs: readonly PendingJob[];
+    /** Latest job presentation, for clients that reconnect. */
+    readonly presentation: Json | null;
+    /** Recent engine events, unredacted; redacted per viewer when sent. */
+    readonly log: readonly Json[];
+    readonly outcome: Outcome | null;
+    readonly startedAt: number;
+    /**
+     * Set while the table is paused (no player connected, D-58): when the pause began. Clocks
+     * keep their deadlines meanwhile; when a player returns, every deadline moves on by the
+     * pause, so no clock or bank is charged for it. Durable, so a pause survives a restart.
+     */
+    readonly pausedAt?: number;
+};
+/** A rematch or end-match offer (section 3.10, D-61). */
+export type OfferRecord = {
+    /** The revision that opened it; answers name it. */
+    readonly id: number;
+    readonly kind: OfferKind;
+    readonly by: SeatId;
+    readonly status: 'open' | 'declined' | 'withdrawn';
+    /** Human seats that accepted, the proposer first. Computer seats accept without being listed. */
+    readonly accepted: readonly SeatId[];
+    readonly declinedBy: SeatId | null;
+    /** An end offer: when the match ends if nobody declines. */
+    readonly endsAt: number | null;
+};
+export type Receipt = {
+    readonly seat: SeatId;
+    readonly id: ActionId;
+    /** Hash of the canonical JSON of { expectedRevision, command or control }. */
+    readonly fingerprint: string;
+    /** The revision the action produced. */
+    readonly revision: number;
+};
+export type RoomRecord = {
+    /** The room record's own schema version. */
+    readonly format: 1;
+    readonly code: RoomCode;
+    /** Bumped by a restore from backup (section 6.6). */
+    readonly epoch: number;
+    /** +1 per persist; guards against two writers (section 4.3). */
+    readonly writes: number;
+    readonly policy: RoomPolicy;
+    readonly phase: RoomPhase;
+    readonly revision: number;
+    /** The game the room plays: the pin of the current match, or the lobby's intended engine. */
+    readonly game: GamePin;
+    /** The configuration the next match starts with. */
+    readonly config: Json;
+    /** The level given to seats filled with the AI. */
+    readonly aiLevel: string | null;
+    readonly seats: readonly SeatRecord[];
+    readonly host: SeatId | null;
+    /** Null in a lobby before the first start. */
+    readonly match: MatchRecord | null;
+    /** The latest rematch or end-match offer; absent in records written before D-61. */
+    readonly offer?: OfferRecord | null;
+    readonly receipts: readonly Receipt[];
+    readonly createdAt: number;
+    readonly updatedAt: number;
+};
+export type Member = {
+    /** Null: spectator. */
+    readonly seat: SeatId | null;
+    /** The wire version this connection speaks. */
+    readonly protocol: number;
+    readonly joinedAt: number;
+};
+/** What the core steps. The adapter holds one per room in memory. */
+export type LiveRoom = {
+    readonly record: RoomRecord;
+    readonly members: ReadonlyMap<ConnId, Member>;
+    /** Claimed human seats with no connection, since when. */
+    readonly absentSince: ReadonlyMap<SeatId, number>;
+    /** Job id → start time, for job timeouts. */
+    readonly jobStartedAt: ReadonlyMap<string, number>;
+    /** Heavy AI: seat → the decisionRevision a `start-ai` is out for. Live-only. */
+    readonly aiInFlight: ReadonlyMap<SeatId, number>;
+    /** Heavy AI: seat → when to ask the pool again after it failed that decision. Live-only. */
+    readonly aiRetry: ReadonlyMap<SeatId, AiRetry>;
+    /** The last alarm the core asked for, so it emits `alarm` only when it changes. */
+    readonly alarmAt: number | null;
+    /** Set by `close`; a closed copy never persists again. */
+    readonly closed: boolean;
+};
+/**
+ * Why the pool gave no answer to a `start-ai`. `busy`: it refused the job unrun. `lost`: a
+ * restart caused by another job ended it. `timeout` and `crashed`: it ran too long or its worker
+ * died while running it. `failed`: the AI's module threw or the job has no module.
+ */
+export type AiFailure = 'busy' | 'lost' | 'timeout' | 'crashed' | 'failed';
+/** A heavy AI decision waiting to be asked again (rule 7). */
+export type AiRetry = {
+    readonly decisionRevision: number;
+    readonly at: number;
+    /** Failed asks for this decision so far, which set the backoff. */
+    readonly failures: number;
+    /** Of those, timeouts and crashes, which count toward `aiAttempts`. */
+    readonly faults: number;
+};
+/** Fresh seeds from the adapter's CSPRNG, for a match that starts in this step. */
+export type MatchSeeds = {
+    readonly engine: RngState;
+    readonly ai: RngState;
+};
+export type RoomCommand = {
+    readonly type: 'join';
+    readonly conn: ConnId;
+    /**
+     * As the client sent it. The core runs the identity filter (`@joystyk/identity/names`) and
+     * gives a refused name a generated one, with a `name-replaced` notice.
+     */
+    readonly name: string;
+    readonly protocol: number;
+    readonly presentedTokenHash: string | null;
+    /** Hash of a fresh token the adapter generated; used only if the core assigns a new seat. */
+    readonly freshTokenHash: string;
+    /** Spectate even if a seat is free. */
+    readonly watch: boolean;
+}
+/** The socket closed. Not a departure: the seat's grace period starts. */
+ | {
+    readonly type: 'leave';
+    readonly conn: ConnId;
+} | {
+    readonly type: 'act';
+    readonly conn: ConnId;
+    readonly id: ActionId;
+    readonly expectedRevision: number;
+    /** Already passed engine.schemas.command. */
+    readonly command: Json;
+} | {
+    readonly type: 'control';
+    readonly conn: ConnId;
+    readonly id: ActionId;
+    readonly expectedRevision: number;
+    readonly control: RoomControl;
+    /** Used only when this control starts a match (start, or the answer that completes a rematch offer). */
+    readonly seeds: MatchSeeds;
+}
+/** The client asked for a full snapshot. */
+ | {
+    readonly type: 'resync';
+    readonly conn: ConnId;
+} | {
+    readonly type: 'timer-fired';
+} | {
+    readonly type: 'job-completed';
+    readonly jobId: string;
+    readonly outcome: JobOutcome;
+}
+/** Heavy AI: the pool's answer to `start-ai`, unparsed, or why there is none. */
+ | {
+    readonly type: 'ai-chosen';
+    readonly seat: SeatId;
+    readonly decisionRevision: number;
+    readonly command: Json;
+} | {
+    readonly type: 'ai-chosen';
+    readonly seat: SeatId;
+    readonly decisionRevision: number;
+    readonly command: null;
+    readonly failure: AiFailure;
+}
+/** First command after loading from storage. */
+ | {
+    readonly type: 'resume';
+} | {
+    readonly type: 'close';
+    readonly reason: 'expired' | 'unload';
+};
+/** One engine input, for the room's replay log (the contract's Replay.inputs). */
+export type LoggedInput = {
+    readonly match: number;
+    readonly revision: number;
+    readonly at: number;
+    /** Job outcomes without their presentation. */
+    readonly input: EngineInput<Json>;
+};
+export type DropReason = 'replaced' | 'left-room' | 'room-closed' | 'room-full';
+export type RoomEffect = 
+/** Save. Always the first effect when the record changed; nothing else happens if it fails. */
+{
+    readonly type: 'persist';
+    readonly record: RoomRecord;
+    readonly inputs: readonly LoggedInput[];
+}
+/** Welcome one connection. With `issueToken`, the adapter adds the fresh token it generated. */
+ | {
+    readonly type: 'welcome';
+    readonly conn: ConnId;
+    readonly message: WelcomeMessage;
+    readonly issueToken: boolean;
+}
+/** Send one message to several connections: every member of a seat, or all spectators. */
+ | {
+    readonly type: 'send';
+    readonly to: readonly ConnId[];
+    readonly message: ServerMessage;
+}
+/** Close a connection the room no longer serves. */
+ | {
+    readonly type: 'drop';
+    readonly conn: ConnId;
+    readonly reason: DropReason;
+}
+/** Wake the room at this time with { type: 'timer-fired' }. Null cancels. */
+ | {
+    readonly type: 'alarm';
+    readonly at: number | null;
+} | {
+    readonly type: 'start-job';
+    readonly jobId: string;
+    readonly kind: string;
+    readonly payload: Json;
+    readonly timeoutMs: number;
+}
+/** Heavy AI: choose on the worker pool. `rng` is this decision's forked stream. */
+ | {
+    readonly type: 'start-ai';
+    readonly seat: SeatId;
+    readonly decisionRevision: number;
+    readonly view: Json;
+    readonly level: string;
+    readonly rng: RngState;
+} | {
+    readonly type: 'log';
+    readonly level: 'info' | 'warn' | 'error';
+    readonly event: string;
+    readonly fields: {
+        readonly [k: string]: Json;
+    };
+};
+export type Step = {
+    readonly room: LiveRoom;
+    readonly effects: readonly RoomEffect[];
+};
+export type RoomError = {
+    readonly code: 'bad-config' | 'bad-policy' | 'init-failed';
+    readonly message: string;
+    /** Server-only diagnostic data. Never serialize the error wholesale to a client. */
+    readonly diagnostic?: {
+        readonly reference: string;
+        readonly error: string;
+    };
+};
+export type CreateParams = {
+    readonly code: RoomCode;
+    readonly policy: RoomPolicy;
+    /** Already passed engine.schemas.config. */
+    readonly config: Json;
+    /** From the adapter's CSPRNG. Used when the match starts at creation (start: 'immediate'). */
+    readonly seeds: MatchSeeds;
+    /** `name` as the client sent it; a name the identity filter refuses becomes a generated one. */
+    readonly creator: {
+        readonly name: string;
+        readonly tokenHash: string;
+    };
+};
+export type CoreLimits = {
+    readonly receiptsPerSeat: number;
+    readonly logEvents: number;
+    readonly aiInputsPerStep: number;
+    readonly resumeGraceMs: number;
+    /** How long an offer to end a match waits for a decline before the match ends (D-61). */
+    readonly endOfferMs: number;
+    /** A heavy AI's first wait before the pool is asked again; each further failure doubles it. */
+    readonly aiRetryMs: number;
+    readonly aiRetryMaxMs: number;
+    /** Timeouts and crashes of one decision before its seat gets the timeout move. */
+    readonly aiAttempts: number;
+};
+export declare const DEFAULT_LIMITS: CoreLimits;
+export type RoomCoreOptions = {
+    readonly engine: AnyDiscreteEngine;
+    /** The build this core runs; `pin.rulesVersion` must equal `engine.rulesVersion`. */
+    readonly pin: GamePin;
+    /** Rebuilds the engine's seeded generator from saved state (usually the kit's `restoreRng`). */
+    readonly rng: (state: RngState) => Rng;
+    /** The manifest's `ai.heavy`: choose on the worker pool (`start-ai`), never inside a step. */
+    readonly heavyAi?: boolean;
+    readonly limits?: Partial<CoreLimits>;
+};
+export interface RoomCore {
+    readonly engine: AnyDiscreteEngine;
+    readonly pin: GamePin;
+    /** A new record. For start: 'immediate', the match is initialized too. */
+    create(params: CreateParams, now: number): Result<RoomRecord, RoomError>;
+    /** Wrap a loaded record. The adapter then steps { type: 'resume' }. */
+    load(record: RoomRecord): LiveRoom;
+    step(room: LiveRoom, command: RoomCommand, now: number): Step;
+}

package/dist/types.js

@@ -0,0 +1,15 @@
+//#region src/types.ts
+var DEFAULT_LIMITS = {
+	receiptsPerSeat: 64,
+	logEvents: 300,
+	aiInputsPerStep: 256,
+	resumeGraceMs: 15e3,
+	endOfferMs: 6e4,
+	aiRetryMs: 1e3,
+	aiRetryMaxMs: 16e3,
+	aiAttempts: 3
+};
+//#endregion
+export { DEFAULT_LIMITS };
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["// The room core's types (room-server.md sections 3.2 to 3.4). A room is a pure value; every\n// change goes through `step(room, command, now)`, which returns the next room and a list of\n// effects for the adapter to carry out.\nimport type {\n  AnyDiscreteEngine,\n  EngineInput,\n  Json,\n  JobOutcome,\n  JobRequest,\n  Outcome,\n  Result,\n  Rng,\n  RngState,\n  SeatId,\n  SeatInfo,\n} from '@joystyk/contracts';\nimport type {\n  ActionId,\n  BankSetting,\n  GamePin,\n  OfferKind,\n  RoomCode,\n  RoomControl,\n  RoomPhase,\n  ServerMessage,\n  WelcomeMessage,\n} from './protocol/index.ts';\n\nexport type {\n  ActionId,\n  BankSetting,\n  GamePin,\n  OfferKind,\n  RoomCode,\n  RoomControl,\n  RoomOffer,\n  RoomPhase,\n} from './protocol/index.ts';\n\n/** Assigned by the adapter to each socket; never persisted. */\nexport type ConnId = string;\n\n/** Per-game defaults come from the manifest; the creator may change some within bounds. */\nexport type RoomPolicy = {\n  readonly seats: { readonly min: number; readonly max: number };\n  /** 'host': a lobby, then the host starts. 'immediate': the match starts at creation with AI in every other seat. */\n  readonly start: 'host' | 'immediate';\n  /** Someone arriving mid-match watches, or takes over an unclaimed AI seat. */\n  readonly lateJoin: 'spectate' | 'take-ai-seat';\n  /** After the grace period, an absent player's seat goes to the AI, has its turns expired, or waits. */\n  readonly absent: 'ai' | 'timeout' | 'wait';\n  readonly graceMs: number;\n  /** Per-move clock; null = off, or a bank runs instead. */\n  readonly decisionMs: number | null;\n  /** A time bank with increment (the manifest's `clock.mode: 'bank'`); when set, decisionMs is null. */\n  readonly bank?: BankSetting | null;\n  /** 0 disables watching. */\n  readonly maxSpectators: number;\n  /** Delete after this long without a change. */\n  readonly retainMs: number;\n};\n\nexport type SeatClaim = { readonly tokenHash: string; readonly name: string };\n\nexport type SeatRecord = {\n  readonly id: SeatId;\n  /** Who holds the seat. Null: open, or played by the AI with nobody to give it back to. */\n  readonly claim: SeatClaim | null;\n  readonly controller: 'human' | 'ai';\n  readonly aiLevel: string | null;\n  readonly ready: boolean;\n};\n\nexport type DecisionClock = {\n  readonly seat: SeatId;\n  /** Epoch ms. */\n  readonly at: number;\n  /** The clock belongs to this decision: it survives changes that leave the seat's decision alone. */\n  readonly decisionRevision: number;\n  /** Bank mode: when the bank starts running (after the playback hold). */\n  readonly startsAt?: number;\n  /** Bank mode: false when the engine's `decisionMs` replaced the bank for this decision. */\n  readonly onBank?: boolean;\n};\n\nexport type PendingJob = {\n  /** Id, kind and payload, from the contract. */\n  readonly request: JobRequest;\n  /** The revision that requested it. */\n  readonly revision: number;\n};\n\nexport type MatchRecord = {\n  /** 1, then +1 per rematch. */\n  readonly number: number;\n  /** Pinned for this match. */\n  readonly game: GamePin;\n  readonly config: Json;\n  /** The seats `init` received: with `seed`, `config` and the input log, the replay. */\n  readonly seats: readonly SeatInfo[];\n  /** The engine rng at init: the replay seed. */\n  readonly seed: RngState;\n  /** Engine state. */\n  readonly state: Json;\n  /** Never sent to a client. */\n  readonly rng: RngState;\n  /**\n   * The AI's stream, kept apart so AI choices never shift the engine's draws. Each decision\n   * forks a child from it; it moves on only when an AI move is accepted (rule 7).\n   */\n  readonly aiRng: RngState;\n  /** Per seat: the last revision that changed its `decisionKey`. */\n  readonly decisionRevision: readonly number[];\n  /** Durable: they survive a restart. */\n  readonly clocks: readonly DecisionClock[];\n  /** Bank mode: each seat's remaining bank in milliseconds. */\n  readonly banks?: readonly number[];\n  readonly jobs: readonly PendingJob[];\n  /** Latest job presentation, for clients that reconnect. */\n  readonly presentation: Json | null;\n  /** Recent engine events, unredacted; redacted per viewer when sent. */\n  readonly log: readonly Json[];\n  readonly outcome: Outcome | null;\n  readonly startedAt: number;\n  /**\n   * Set while the table is paused (no player connected, D-58): when the pause began. Clocks\n   * keep their deadlines meanwhile; when a player returns, every deadline moves on by the\n   * pause, so no clock or bank is charged for it. Durable, so a pause survives a restart.\n   */\n  readonly pausedAt?: number;\n};\n\n/** A rematch or end-match offer (section 3.10, D-61). */\nexport type OfferRecord = {\n  /** The revision that opened it; answers name it. */\n  readonly id: number;\n  readonly kind: OfferKind;\n  readonly by: SeatId;\n  readonly status: 'open' | 'declined' | 'withdrawn';\n  /** Human seats that accepted, the proposer first. Computer seats accept without being listed. */\n  readonly accepted: readonly SeatId[];\n  readonly declinedBy: SeatId | null;\n  /** An end offer: when the match ends if nobody declines. */\n  readonly endsAt: number | null;\n};\n\nexport type Receipt = {\n  readonly seat: SeatId;\n  readonly id: ActionId;\n  /** Hash of the canonical JSON of { expectedRevision, command or control }. */\n  readonly fingerprint: string;\n  /** The revision the action produced. */\n  readonly revision: number;\n};\n\nexport type RoomRecord = {\n  /** The room record's own schema version. */\n  readonly format: 1;\n  readonly code: RoomCode;\n  /** Bumped by a restore from backup (section 6.6). */\n  readonly epoch: number;\n  /** +1 per persist; guards against two writers (section 4.3). */\n  readonly writes: number;\n  readonly policy: RoomPolicy;\n  readonly phase: RoomPhase;\n  readonly revision: number;\n  /** The game the room plays: the pin of the current match, or the lobby's intended engine. */\n  readonly game: GamePin;\n  /** The configuration the next match starts with. */\n  readonly config: Json;\n  /** The level given to seats filled with the AI. */\n  readonly aiLevel: string | null;\n  readonly seats: readonly SeatRecord[];\n  readonly host: SeatId | null;\n  /** Null in a lobby before the first start. */\n  readonly match: MatchRecord | null;\n  /** The latest rematch or end-match offer; absent in records written before D-61. */\n  readonly offer?: OfferRecord | null;\n  readonly receipts: readonly Receipt[];\n  readonly createdAt: number;\n  readonly updatedAt: number;\n};\n\nexport type Member = {\n  /** Null: spectator. */\n  readonly seat: SeatId | null;\n  /** The wire version this connection speaks. */\n  readonly protocol: number;\n  readonly joinedAt: number;\n};\n\n/** What the core steps. The adapter holds one per room in memory. */\nexport type LiveRoom = {\n  readonly record: RoomRecord;\n  readonly members: ReadonlyMap<ConnId, Member>;\n  /** Claimed human seats with no connection, since when. */\n  readonly absentSince: ReadonlyMap<SeatId, number>;\n  /** Job id → start time, for job timeouts. */\n  readonly jobStartedAt: ReadonlyMap<string, number>;\n  /** Heavy AI: seat → the decisionRevision a `start-ai` is out for. Live-only. */\n  readonly aiInFlight: ReadonlyMap<SeatId, number>;\n  /** Heavy AI: seat → when to ask the pool again after it failed that decision. Live-only. */\n  readonly aiRetry: ReadonlyMap<SeatId, AiRetry>;\n  /** The last alarm the core asked for, so it emits `alarm` only when it changes. */\n  readonly alarmAt: number | null;\n  /** Set by `close`; a closed copy never persists again. */\n  readonly closed: boolean;\n};\n\n/**\n * Why the pool gave no answer to a `start-ai`. `busy`: it refused the job unrun. `lost`: a\n * restart caused by another job ended it. `timeout` and `crashed`: it ran too long or its worker\n * died while running it. `failed`: the AI's module threw or the job has no module.\n */\nexport type AiFailure = 'busy' | 'lost' | 'timeout' | 'crashed' | 'failed';\n\n/** A heavy AI decision waiting to be asked again (rule 7). */\nexport type AiRetry = {\n  readonly decisionRevision: number;\n  readonly at: number;\n  /** Failed asks for this decision so far, which set the backoff. */\n  readonly failures: number;\n  /** Of those, timeouts and crashes, which count toward `aiAttempts`. */\n  readonly faults: number;\n};\n\n/** Fresh seeds from the adapter's CSPRNG, for a match that starts in this step. */\nexport type MatchSeeds = { readonly engine: RngState; readonly ai: RngState };\n\nexport type RoomCommand =\n  | {\n      readonly type: 'join';\n      readonly conn: ConnId;\n      /**\n       * As the client sent it. The core runs the identity filter (`@joystyk/identity/names`) and\n       * gives a refused name a generated one, with a `name-replaced` notice.\n       */\n      readonly name: string;\n      readonly protocol: number;\n      readonly presentedTokenHash: string | null;\n      /** Hash of a fresh token the adapter generated; used only if the core assigns a new seat. */\n      readonly freshTokenHash: string;\n      /** Spectate even if a seat is free. */\n      readonly watch: boolean;\n    }\n  /** The socket closed. Not a departure: the seat's grace period starts. */\n  | { readonly type: 'leave'; readonly conn: ConnId }\n  | {\n      readonly type: 'act';\n      readonly conn: ConnId;\n      readonly id: ActionId;\n      readonly expectedRevision: number;\n      /** Already passed engine.schemas.command. */\n      readonly command: Json;\n    }\n  | {\n      readonly type: 'control';\n      readonly conn: ConnId;\n      readonly id: ActionId;\n      readonly expectedRevision: number;\n      readonly control: RoomControl;\n      /** Used only when this control starts a match (start, or the answer that completes a rematch offer). */\n      readonly seeds: MatchSeeds;\n    }\n  /** The client asked for a full snapshot. */\n  | { readonly type: 'resync'; readonly conn: ConnId }\n  | { readonly type: 'timer-fired' }\n  | { readonly type: 'job-completed'; readonly jobId: string; readonly outcome: JobOutcome }\n  /** Heavy AI: the pool's answer to `start-ai`, unparsed, or why there is none. */\n  | { readonly type: 'ai-chosen'; readonly seat: SeatId; readonly decisionRevision: number; readonly command: Json }\n  | {\n      readonly type: 'ai-chosen';\n      readonly seat: SeatId;\n      readonly decisionRevision: number;\n      readonly command: null;\n      readonly failure: AiFailure;\n    }\n  /** First command after loading from storage. */\n  | { readonly type: 'resume' }\n  | { readonly type: 'close'; readonly reason: 'expired' | 'unload' };\n\n/** One engine input, for the room's replay log (the contract's Replay.inputs). */\nexport type LoggedInput = {\n  readonly match: number;\n  readonly revision: number;\n  readonly at: number;\n  /** Job outcomes without their presentation. */\n  readonly input: EngineInput<Json>;\n};\n\nexport type DropReason = 'replaced' | 'left-room' | 'room-closed' | 'room-full';\n\nexport type RoomEffect =\n  /** Save. Always the first effect when the record changed; nothing else happens if it fails. */\n  | { readonly type: 'persist'; readonly record: RoomRecord; readonly inputs: readonly LoggedInput[] }\n  /** Welcome one connection. With `issueToken`, the adapter adds the fresh token it generated. */\n  | { readonly type: 'welcome'; readonly conn: ConnId; readonly message: WelcomeMessage; readonly issueToken: boolean }\n  /** Send one message to several connections: every member of a seat, or all spectators. */\n  | { readonly type: 'send'; readonly to: readonly ConnId[]; readonly message: ServerMessage }\n  /** Close a connection the room no longer serves. */\n  | { readonly type: 'drop'; readonly conn: ConnId; readonly reason: DropReason }\n  /** Wake the room at this time with { type: 'timer-fired' }. Null cancels. */\n  | { readonly type: 'alarm'; readonly at: number | null }\n  | {\n      readonly type: 'start-job';\n      readonly jobId: string;\n      readonly kind: string;\n      readonly payload: Json;\n      readonly timeoutMs: number;\n    }\n  /** Heavy AI: choose on the worker pool. `rng` is this decision's forked stream. */\n  | {\n      readonly type: 'start-ai';\n      readonly seat: SeatId;\n      readonly decisionRevision: number;\n      readonly view: Json;\n      readonly level: string;\n      readonly rng: RngState;\n    }\n  | {\n      readonly type: 'log';\n      readonly level: 'info' | 'warn' | 'error';\n      readonly event: string;\n      readonly fields: { readonly [k: string]: Json };\n    };\n\nexport type Step = {\n  readonly room: LiveRoom;\n  readonly effects: readonly RoomEffect[];\n};\n\nexport type RoomError = {\n  readonly code: 'bad-config' | 'bad-policy' | 'init-failed';\n  readonly message: string;\n  /** Server-only diagnostic data. Never serialize the error wholesale to a client. */\n  readonly diagnostic?: { readonly reference: string; readonly error: string };\n};\n\nexport type CreateParams = {\n  readonly code: RoomCode;\n  readonly policy: RoomPolicy;\n  /** Already passed engine.schemas.config. */\n  readonly config: Json;\n  /** From the adapter's CSPRNG. Used when the match starts at creation (start: 'immediate'). */\n  readonly seeds: MatchSeeds;\n  /** `name` as the client sent it; a name the identity filter refuses becomes a generated one. */\n  readonly creator: { readonly name: string; readonly tokenHash: string };\n};\n\nexport type CoreLimits = {\n  readonly receiptsPerSeat: number;\n  readonly logEvents: number;\n  readonly aiInputsPerStep: number;\n  readonly resumeGraceMs: number;\n  /** How long an offer to end a match waits for a decline before the match ends (D-61). */\n  readonly endOfferMs: number;\n  /** A heavy AI's first wait before the pool is asked again; each further failure doubles it. */\n  readonly aiRetryMs: number;\n  readonly aiRetryMaxMs: number;\n  /** Timeouts and crashes of one decision before its seat gets the timeout move. */\n  readonly aiAttempts: number;\n};\n\nexport const DEFAULT_LIMITS: CoreLimits = {\n  receiptsPerSeat: 64,\n  logEvents: 300,\n  aiInputsPerStep: 256,\n  resumeGraceMs: 15_000,\n  endOfferMs: 60_000,\n  aiRetryMs: 1_000,\n  aiRetryMaxMs: 16_000,\n  aiAttempts: 3,\n};\n\nexport type RoomCoreOptions = {\n  readonly engine: AnyDiscreteEngine;\n  /** The build this core runs; `pin.rulesVersion` must equal `engine.rulesVersion`. */\n  readonly pin: GamePin;\n  /** Rebuilds the engine's seeded generator from saved state (usually the kit's `restoreRng`). */\n  readonly rng: (state: RngState) => Rng;\n  /** The manifest's `ai.heavy`: choose on the worker pool (`start-ai`), never inside a step. */\n  readonly heavyAi?: boolean;\n  readonly limits?: Partial<CoreLimits>;\n};\n\nexport interface RoomCore {\n  readonly engine: AnyDiscreteEngine;\n  readonly pin: GamePin;\n  /** A new record. For start: 'immediate', the match is initialized too. */\n  create(params: CreateParams, now: number): Result<RoomRecord, RoomError>;\n  /** Wrap a loaded record. The adapter then steps { type: 'resume' }. */\n  load(record: RoomRecord): LiveRoom;\n  step(room: LiveRoom, command: RoomCommand, now: number): Step;\n}\n"],"mappings":";AA2WA,IAAa,iBAA6B;CACxC,iBAAiB;CACjB,WAAW;CACX,iBAAiB;CACjB,eAAe;CACf,YAAY;CACZ,WAAW;CACX,cAAc;CACd,YAAY;AACd"}

package/package.json

@@ -1,20 +1,65 @@
 {
   "name": "@joystyk/rooms",
-  "version": "0.0.0",
-  "description": "Reserved for the first Joystyk library release.",
+  "version": "0.2.0",
+  "description": "The room server: a pure room core, the versioned wire protocol and a Node adapter (WebSockets, SQLite, timers, worker jobs).",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol/index.d.ts",
+      "default": "./dist/protocol/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.js"
+    }
+  },
+  "dependencies": {
+    "ws": "8.22.0",
+    "zod": "4.6.5",
+    "@joystyk/contracts": "0.2.0",
+    "@joystyk/ops": "0.2.0",
+    "@joystyk/kit": "0.2.0",
+    "@joystyk/identity": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "@types/ws": "8.18.1",
+    "fast-check": "4.10.2",
+    "typescript": "5.9.3",
+    "vite": "8.3.3",
+    "vitest": "4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=24.15.0"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/joystyk-games/game-libraries.git",
     "directory": "packages/rooms"
   },
-  "homepage": "https://github.com/joystyk-games/game-libraries",
-  "files": [
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ],
-  "publishConfig": {
-    "access": "public"
+  "homepage": "https://github.com/joystyk-games/game-libraries/tree/main/packages/rooms#readme",
+  "bugs": {
+    "url": "https://github.com/joystyk-games/game-libraries/issues"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../scripts/build-package.ts"
   }
-}
+}