@joystyk/rooms 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# @joystyk/rooms
+
+## 0.2.0
+
+### Minor Changes
+
+- bb095c7: A heavy AI the job pool couldn't answer is asked again with backoff instead of playing the
+  timeout move. `ai-chosen` without a command now carries the pool's `failure`, `LiveRoom` gains
+  `aiRetry`, and `CoreLimits` gains `aiRetryMs`, `aiRetryMaxMs` and `aiAttempts`. The worker pool
+  runs each worker's jobs one at a time, counts a job's timeout from when it starts, and reports
+  `busy`, `lost` and `crashed` separately (`PoolOutcome`).
+
+### Patch Changes
+
+- bb095c7: Share canonical IPv4 and IPv6 /64 rate-limit keys across Node services. Keep room
+  initialization diagnostics on the server behind a client-safe reference, and expire old
+  message-rate strikes. Extend hidden-information conformance checks with transition-aware
+  perturbations so private events remain testable when recipients gain cards.
+- Updated dependencies [bb095c7]
+- Updated dependencies [bb095c7]
+- Updated dependencies [bb095c7]
+  - @joystyk/contracts@0.2.0
+  - @joystyk/ops@0.2.0
+  - @joystyk/identity@0.2.0
+  - @joystyk/kit@0.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- Prepare the first compiled library release: ESM and API declarations for every public entry point, runtime assets, and checks against installed npm tarballs. Games and applications remain private.
+
+### Patch Changes
+
+- Updated dependencies
+  - @joystyk/contracts@0.1.0
+  - @joystyk/kit@0.1.0
+  - @joystyk/identity@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joystyk contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,36 @@
+Third-party material in the Joystyk library release
+
+This notice preserves third-party attribution. Original Joystyk code in the 17
+platform libraries under packages/ uses the MIT license in packages/LICENSE.
+That choice does not license the private applications, games or other repository
+material, and does not replace the third-party terms below.
+
+@joystyk/contracts
+------------------
+Standard Schema v1 type definitions from @standard-schema/spec 1.1.0:
+https://github.com/standard-schema/standard-schema
+https://standardschema.dev
+Copyright (c) 2024 Colin McDonnell. MIT License.
+The complete license and source/change notes accompany the distributed
+dist/standard-schema.d.ts definitions. Changes: individually exported declarations
+and formatting; the declarations themselves are unchanged.
+
+@joystyk/identity and @joystyk/content
+-----------------------------------
+Word blocklists derived from List of Dirty, Naughty, Obscene, and Otherwise Bad
+Words, copyright Shutterstock, Inc. and contributors:
+https://github.com/LDNOOBW/List-of-Dirty-Naughty-Obscene-and-Otherwise-Bad-Words
+Licensed under Creative Commons Attribution 4.0 International:
+https://creativecommons.org/licenses/by/4.0/
+Identity uses the English list at commit
+5faf2ba42d7b1c0977169ec3611df25a3c08eb13. Changes include reducing or dropping
+phrases, dropping words with everyday meanings, substituting stems for inflections
+and adding entries. Identity's README and content's lists/blocklist.txt retain
+their source-specific provenance and changes.
+
+@joystyk/content
+---------------
+SCOWL-derived common, vocabulary and ranked word lists use SCOWL 2020.12.07.
+Their complete source licenses and attribution accompany the package in
+lists/SCOWL-COPYRIGHT. Word-list transformations and build provenance are described
+in the package README. Preserve that copyright file when redistributing the lists.

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# @joystyk/rooms
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The room server for every server-authoritative multiplayer game: a pure room core, the
+versioned wire protocol, and a Node adapter that runs the core on WebSockets, SQLite, one
+timer per room and a `worker_threads` job pool. The design is
+room-server.md (Joystyk host reference); its "Changes from implementation"
+section lists where this package departs from the first draft.
+
+## npm package
+
+The first `0.1.0` release is being prepared; it has not been published. Once available:
+
+```sh
+npm install @joystyk/rooms
+```
+
+Node consumers require Node 24.15 or later. Browser entry points require a modern
+browser and should be loaded in the browser.
+
+| Import | Format |
+| --- | --- |
+| `@joystyk/rooms` | ES module and TypeScript declarations |
+| `@joystyk/rooms/protocol` | ES module and TypeScript declarations |
+| `@joystyk/rooms/node` | ES module and TypeScript declarations |
+
+Only the entries listed above are public API. Installed packages contain compiled ESM,
+type declarations and runtime assets. Repository-relative links describe the Joystyk
+workspace and are not needed to use the npm package.
+
+| Entry | Kind | Contents |
+| --- | --- | --- |
+| `@joystyk/rooms` | Pure | `createRoomCore`, the room types, the record schema and migrations, `policyFromManifest`, `admitName` |
+| `@joystyk/rooms/protocol` | Pure (`zod/mini`) | Wire schemas and types, `PROTOCOL_VERSION`, close and rejection codes |
+| `@joystyk/rooms/node` | Node | `createRoomServer`, `RoomHost`, `openSqliteStore`, `workerJobPool`, `createEngineRegistry` |
+
+The `session` package, and the `p2p` package that comes after launch (host policy), may import
+`@joystyk/rooms/protocol` and nothing else from here. The service that deploys all of this
+is `apps/rooms` (`@joystyk/rooms-server`).
+
+## The core
+
+A room is a value. Everything that happens to it goes through one function:
+
+```ts
+import { createRoomCore } from '@joystyk/rooms';
+
+const core = createRoomCore({ engine, pin: { id: 'hearts', build: '1.4.0', rulesVersion: 3, saveVersion: 2 }, rng: sfc32 });
+const created = core.create({ code, policy, config, seeds, creator: { name, tokenHash } }, now);
+let room = core.load(created.value);
+const { room: next, effects } = core.step(room, { type: 'resume' }, now);
+```
+
+`step(room, command, now)` reads no clock, randomness, storage or network. Commands are
+`join`, `leave`, `act`, `control` (ready, settings, fill-with-ai, remove-seat, start,
+offer, accept, decline, withdraw, leave-seat, resign), `resync`, `timer-fired`, `job-completed`, `ai-chosen`,
+`resume` and `close`. Effects are data for the adapter: `persist` (always first, at most
+once), `welcome`, `send`, `drop`, `alarm`, `start-job`, `start-ai` and `log`.
+
+What the core guarantees, each covered by the property tests in `core.property.test.ts`:
+
+- **Deterministic.** The same room, command and `now` give deeply equal steps.
+- **Persist before broadcast.** If the record changed, the first effect saves it; a
+  rejection changes nothing durable.
+- **Per-seat staleness.** An action is stale only if the seat's `decisionKey` changed
+  after the revision the client saw, so simultaneous moves aren't refused.
+- **Receipts.** A retried action ID with the same payload gets its original receipt, even
+  after a restart; the same ID with a different payload is refused.
+- **Clocks as data.** Deadlines live in the record; whatever is due at `now` applies before
+  the command. A timer that fires early, late or twice can't apply a stale move. A room
+  runs a per-move clock or a time bank with increment (`policy.bank`); banks are charged
+  from the record alone, never for a playback hold.
+- **The AI's stream.** Each AI decision gets a child forked from `aiRng` with the kit's
+  `forkRng`; the stream moves only when an AI move is accepted. A heavy AI
+  (`heavyAi: true`) never chooses inside a step: the core emits `start-ai`, the adapter runs
+  it on the pool, and `ai-chosen` applies only if the seat still waits on that decision.
+- **No leaks.** Each seat receives `viewFor(state, seat)` and `eventFor(event, seat)`;
+  spectators get the `null` view.
+- **Paused when empty.** With no player connected, no AI move, clock, offer or absence
+  policy runs. The pause is recorded (`match.pausedAt`), and when a player returns every
+  deadline moves on by its length, so no clock or bank is charged for it (host policy).
+- **Offers.** Any seated player offers a rematch, or to end a match early; the others
+  accept or decline, and the proposer may withdraw. A rematch starts once every seated
+  player has accepted (computer seats accept on their own); an early end needs every other
+  connected player, or a minute with nobody declining, and leaves no result (host policy).
+- **Pinned versions.** A match keeps its game build and rules version; a rematch starts on
+  the newest engine.
+- **Filtered names.** The creator's name and every name that claims a seat pass
+  `checkDisplayName` from `@joystyk/identity/names`, the only part of identity this package
+  imports. A refused name becomes a generated one, seeded by the room's code, epoch, revision
+  and seat, so the step stays deterministic; the player gets a `name-replaced` notice that
+  says why, and `POST /api/rooms` answers with the seat's `name` and the same `notice`.
+
+The core takes the engine's seeded generator as an argument (`rng: (state) => Rng`; the
+service passes the kit's `restoreRng`). The adapter supplies fresh seeds and token hashes; no
+secret ever enters the core.
+
+## The Node adapter
+
+```ts
+import { createEngineRegistry, createRoomServer, openSqliteStore, workerJobPool } from '@joystyk/rooms/node';
+
+const store = await openSqliteStore('/data/rooms.sqlite');
+const registry = createEngineRegistry([{ pin, engine, policy, jobs: { throw: new URL('./jobs/throw.worker.ts', import.meta.url) } }], sfc32);
+const server = createRoomServer({ store, registry, seeds, pool: workerJobPool({ workers: 1, module: registry.jobModule }), publicOrigin });
+await server.listen(8787);
+process.once('SIGTERM', () => void server.drain());
+```
+
+- **HTTP.** `POST /api/rooms` creates a room and returns its code with the creator's seat
+  token; `GET /api/rooms/:code` describes it; `GET /api/rooms/games` lists the games the
+  registry hosts and the protocol versions (`HostedGames`), which the launcher reads before
+  offering Online with friends; `/healthz` and `/readyz` serve Compose.
+- **WebSocket** at `/ws`. Messages are decoded with the protocol schemas, then the game's
+  own command schema. The server answers each connection in the protocol version it joined
+  with.
+- **Persistence.** `node:sqlite` in WAL mode. Each persist is one transaction that updates
+  the row only if its `writes` count matches, so a second writer gets `conflict` and
+  unloads. A failed write keeps the old state, sends nothing and retries. Schema migrations
+  run at start-up, a newer database is refused, and corrupt rows move to `room_archive`.
+- **Limits.** Payload size, a message-rate token bucket, rooms per address per hour,
+  unknown-code joins per address, connections per address and in total, rooms in memory,
+  spectators per room, outgoing buffer size and a WebSocket ping heartbeat. The client address
+  is read only from a trusted proxy (an IP or CIDR range).
+- **Jobs.** A game's `jobs/<kind>.worker.ts` default-exports `(payload) => JobOutcome`; its
+  `jobs/ai.worker.ts` (heavy AI) maps `{ view, seat, level, rng }` to a command. The pool
+  bounds queued work, times out stuck jobs from when they start (a heavy AI after
+  `aiTimeoutMs`) and restarts the worker. A heavy AI the pool couldn't answer is asked again
+  with backoff.
+- **Drain and resume.** `drain()` refuses new work, waits for running jobs, sends
+  `closing` and closes with 1012. On start, rooms with an outstanding job load at once so
+  the job re-runs; other rooms load when someone joins.
+- **Logs.** One JSON object per line, never with tokens, names, addresses or game state.
+
+## Tests
+
+| File | What it proves |
+| --- | --- |
+| `core.test.ts` | Seats and display names, receipts, stale and future revisions, controls, AI handover, the host, clocks, jobs, failures |
+| `core.clocks-ai.test.ts` | Time banks, the AI stream, heavy AI |
+| `core.pause.test.ts` | A paused table: clocks stop and resume, banks are charged only for live time, a pause survives a restart |
+| `core.offers.test.ts` | Rematch and end-match offers: offer, accept, decline, withdraw, computer seats accepting, the one-minute end, a pause during it |
+| `core.property.test.ts` | The invariants above, under random command sequences for five set-ups: hidden hands, AI handover, heavy AI, a time bank and a simultaneous phase |
+| `protocol/protocol.test.ts` | Message schemas, and that every message the core sends decodes |
+| `node/store.test.ts` | The SQLite store on a real file: conflicts, migrations, quarantine, backups |
+| `node/host.test.ts` | Restart and resume, a failing store, two writers, jobs that survive a restart |
+| `node/server.test.ts` | Two real WebSocket clients: join, play, reconnect, newest tab wins, spectators, a replaced name, limits, drain |
+| `node/jobs.test.ts` | The `worker_threads` pool with real worker modules |
+
+The test games live in `src/__tests__/fixtures.ts`: Nim (turn-based), Peek (hidden hands,
+a job, an AI) and Pass (a simultaneous phase whose decision key ignores who has passed).

package/dist/canonical.d.ts

@@ -0,0 +1,10 @@
+import type { Json } from '@joystyk/contracts';
+/** JSON with object keys sorted, so equal values always produce the same text. */
+export declare const canonicalJson: (value: Json) => string;
+/**
+ * A 64-bit hash of a string as 16 hex digits (two independent 32-bit FNV-1a style lanes).
+ * Not cryptographic: it only tells a retried action from a different one with the same ID.
+ */
+export declare const hashText: (text: string) => string;
+/** The receipt fingerprint of an action: canonical JSON of what the client sent, hashed. */
+export declare const fingerprint: (value: Json) => string;

package/dist/canonical.js

@@ -0,0 +1,30 @@
+//#region src/canonical.ts
+/** JSON with object keys sorted, so equal values always produce the same text. */
+var canonicalJson = (value) => {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+	const object = value;
+	return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`).join(",")}}`;
+};
+/**
+* A 64-bit hash of a string as 16 hex digits (two independent 32-bit FNV-1a style lanes).
+* Not cryptographic: it only tells a retried action from a different one with the same ID.
+*/
+var hashText = (text) => {
+	let a = 2166136261;
+	let b = 16777619 ^ text.length;
+	for (let i = 0; i < text.length; i += 1) {
+		const code = text.charCodeAt(i);
+		a = Math.imul(a ^ code, 16777619);
+		b = Math.imul(b ^ code, 1540483477);
+		b ^= b >>> 13;
+	}
+	const hex = (n) => (n >>> 0).toString(16).padStart(8, "0");
+	return hex(a) + hex(b);
+};
+/** The receipt fingerprint of an action: canonical JSON of what the client sent, hashed. */
+var fingerprint = (value) => hashText(canonicalJson(value));
+//#endregion
+export { canonicalJson, fingerprint, hashText };
+
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","names":[],"sources":["../src/canonical.ts"],"sourcesContent":["// Canonical JSON and a small pure hash, for receipt fingerprints and change detection. Pure\n// and deterministic in every JavaScript engine: integer arithmetic through Math.imul only.\nimport type { Json } from '@joystyk/contracts';\n\n/** JSON with object keys sorted, so equal values always produce the same text. */\nexport const canonicalJson = (value: Json): string => {\n  if (value === null || typeof value !== 'object') return JSON.stringify(value);\n  if (Array.isArray(value)) return `[${value.map((item: Json) => canonicalJson(item)).join(',')}]`;\n  const object = value as { readonly [key: string]: Json };\n  const keys = Object.keys(object).sort();\n  return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key] as Json)}`).join(',')}}`;\n};\n\n/**\n * A 64-bit hash of a string as 16 hex digits (two independent 32-bit FNV-1a style lanes).\n * Not cryptographic: it only tells a retried action from a different one with the same ID.\n */\nexport const hashText = (text: string): string => {\n  let a = 0x811c9dc5;\n  let b = 0x01000193 ^ text.length;\n  for (let i = 0; i < text.length; i += 1) {\n    const code = text.charCodeAt(i);\n    a = Math.imul(a ^ code, 0x01000193);\n    b = Math.imul(b ^ code, 0x5bd1e995);\n    b ^= b >>> 13;\n  }\n  const hex = (n: number): string => (n >>> 0).toString(16).padStart(8, '0');\n  return hex(a) + hex(b);\n};\n\n/** The receipt fingerprint of an action: canonical JSON of what the client sent, hashed. */\nexport const fingerprint = (value: Json): string => hashText(canonicalJson(value));\n"],"mappings":";;AAKA,IAAa,iBAAiB,UAAwB;CACpD,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU,OAAO,KAAK,UAAU,KAAK;CAC5E,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,IAAI,MAAM,KAAK,SAAe,cAAc,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE;CAC9F,MAAM,SAAS;CAEf,OAAO,IADM,OAAO,KAAK,MAAM,CAAC,CAAC,KACtB,CAAA,CAAK,KAAK,QAAQ,GAAG,KAAK,UAAU,GAAG,EAAE,GAAG,cAAc,OAAO,IAAY,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE;AACzG;;;;;AAMA,IAAa,YAAY,SAAyB;CAChD,IAAI,IAAI;CACR,IAAI,IAAI,WAAa,KAAK;CAC1B,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK,GAAG;EACvC,MAAM,OAAO,KAAK,WAAW,CAAC;EAC9B,IAAI,KAAK,KAAK,IAAI,MAAM,QAAU;EAClC,IAAI,KAAK,KAAK,IAAI,MAAM,UAAU;EAClC,KAAK,MAAM;CACb;CACA,MAAM,OAAO,OAAuB,MAAM,EAAA,CAAG,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG;CACzE,OAAO,IAAI,CAAC,IAAI,IAAI,CAAC;AACvB;;AAGA,IAAa,eAAe,UAAwB,SAAS,cAAc,KAAK,CAAC"}

package/dist/core.d.ts

@@ -0,0 +1,3 @@
+import { type RoomCore, type RoomCoreOptions } from './types.js';
+/** Binds the core to one engine at one rules version. */
+export declare const createRoomCore: (options: RoomCoreOptions) => RoomCore;