@table-games-engine/nakama-adapter 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Dmitry Kucher
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -1,3 +1,323 @@
-# Temporary Holding Version
+# `@table-games-engine/nakama-adapter`
 
-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.
+Nakama runtime bindings for the `@table-games-engine/core` engine.
+
+This package wires the deterministic, in-process `Engine` from
+`@table-games-engine/core` (and the persistence layer from
+`@table-games-engine/persistence`) into a Nakama TypeScript-runtime
+`MatchHandler<T>` so that multiple players can connect via WebSocket and
+play a turn-based card / tabletop game implemented as a `GameManifest`.
+
+For the **normative behaviour contract** (lifecycle, sequential processing,
+persistence, recovery, timeouts) see
+[`docs/normative/platforms/nakama.md`](../../docs/normative/platforms/nakama.md).
+This README is the **operator-facing usage guide** — how to wire the
+module into Nakama, what to configure, and how to extend it with
+platform plugins.
+
+---
+
+## What this package gives you
+
+- A factory `createMatchHandler(opts)` that returns a Nakama
+  `MatchHandler<NkMatchInternalState>` implementing every callback
+  Nakama needs (`matchInit`, `matchJoinAttempt`, `matchJoin`,
+  `matchLeave`, `matchLoop`, `matchSignal`, `matchTerminate`).
+- A `GameRegistry` for resolving `gameId -> { manifest, handlers, setup }`
+  at `matchInit` time, so a single Nakama runtime can host multiple
+  game definitions.
+- An `IdempotencyCache` for absorbing client retries.
+- A `parseInbound`/`serializeOutbound` JSON wire format, opcode
+  constants (`OPCODES`), per-presence broadcast filtering
+  (`broadcastViews`), action timeouts (`checkTimeouts`),
+  reconnection-aware joins, and a `NakamaPlatformPlugin` extension hook.
+- Persistence wiring to `@table-games-engine/persistence`: every engine
+  transition's events are appended; snapshots are written per the
+  configured `SnapshotPolicy`.
+
+---
+
+## Wiring into a Nakama TypeScript runtime
+
+Nakama runs your TS code via the `nakama-runtime` Node host, with an
+`InitModule(ctx, logger, nk, initializer)` entry point. A minimal
+`init.ts` looks like this:
+
+```ts
+// init.ts
+import {
+  createMatchHandler,
+  GameRegistry,
+  IdempotencyCache,
+} from '@table-games-engine/nakama-adapter';
+import { SqliteAdapter } from '@table-games-engine/persistence';
+import { everyNTransitions } from '@table-games-engine/persistence';
+
+import { registerMyGame } from './games/my-game.js';
+
+const MATCH_HANDLER_NAME = 'tabletop_match';
+
+const registry = new GameRegistry();
+registerMyGame(registry); // calls registry.register({ gameId, manifest, handlers, setup, winChecker })
+
+const idempotencyCache = new IdempotencyCache();
+
+const adapter = new SqliteAdapter({
+  path: process.env['ENGINE_DB_PATH'] ?? '/data/engine.db',
+});
+
+const handler = createMatchHandler({
+  registry,
+  idempotencyCache,
+  adapter,
+  policy: everyNTransitions(50),
+  ownerNode: process.env['NAKAMA_NODE_ID'] ?? 'node-A',
+  leaseSeconds: 60,
+  timeout: { timeoutMs: 30_000 },
+  plugins: [
+    /* analytics, audit, etc. — see "Plugins" below */
+  ],
+});
+
+function InitModule(
+  _ctx: nkruntime.Context,
+  logger: nkruntime.Logger,
+  _nk: nkruntime.Nakama,
+  initializer: nkruntime.Initializer,
+): void {
+  initializer.registerMatch(MATCH_HANDLER_NAME, handler);
+  logger.info('registered match handler %s', MATCH_HANDLER_NAME);
+}
+
+!InitModule && InitModule;
+```
+
+Then create a match from your matchmaker / API hook:
+
+```ts
+const matchId = nk.matchCreate(MATCH_HANDLER_NAME, {
+  gameId: 'my-game',
+  // optional — handler will mint one via `matchIdFactory` or `match-<now>` if absent
+  matchId: 'duel-12345',
+  // comma-separated; setup() receives them
+  playerIds: 'alice,bob',
+  config: JSON.stringify({ /* game-instance options */ }),
+});
+```
+
+---
+
+## Environment variables
+
+The adapter itself reads no env vars directly — they're conventions for
+the `init.ts` shim above. Recommended:
+
+| Variable             | Purpose                                                                 |
+| -------------------- | ----------------------------------------------------------------------- |
+| `ENGINE_DB_PATH`     | Path to the SQLite DB used by `SqliteAdapter` for events + snapshots.   |
+| `ENGINE_DB_DSN`      | If using a network-backed adapter (e.g. Postgres), connection DSN.       |
+| `NAKAMA_NODE_ID`     | Node identifier passed to `acquireOwnership(matchId, node, leaseSec)`.  |
+| `ENGINE_SNAPSHOT_N`  | Override `everyNTransitions(N)` cadence at boot.                         |
+| `ENGINE_TIMEOUT_MS`  | Default per-action timeout for `checkTimeouts`.                          |
+| `ENGINE_LEASE_SEC`   | Ownership lease duration in seconds (default 60).                        |
+
+These are NOT consumed by the package — your `init.ts` is responsible
+for plumbing them into `createMatchHandler`'s options. The package
+stays config-agnostic.
+
+---
+
+## Game registration pattern
+
+A "game" is the triple `(manifest, handlers, setup)` registered against
+a `gameId`. Call `registry.register` once at module init:
+
+```ts
+import { GameRegistry } from '@table-games-engine/nakama-adapter';
+import { manifest, handlers, setup, winChecker } from './my-game.js';
+
+export function registerMyGame(registry: GameRegistry): void {
+  registry.register({
+    gameId: 'my-game',
+    manifest,
+    handlers,
+    setup,         // (matchId, playerIds, config, { now }) => MatchState
+    winChecker,    // optional WinConditionChecker
+  });
+}
+```
+
+Multiple games can coexist behind a single Nakama match-handler name —
+`matchInit` resolves the entry by the `gameId` parameter.
+
+---
+
+## Persistence
+
+When `adapter` is supplied to `createMatchHandler`:
+
+- `matchInit` persists the initial state as **snapshot v0**
+  (`adapter.persistSnapshot(matchId, state, checksum)`).
+- If `ownerNode` is also set, `matchInit` calls
+  `adapter.acquireOwnership(matchId, ownerNode, leaseSeconds)`. Failures
+  are logged via `logger.error` but do not abort match creation; for
+  hard-fail semantics, pre-acquire the lease in your matchmaker.
+- Each engine transition (player action, stack drain, timeouts, ejects)
+  appends events via `adapter.appendEvents(matchId, transition.toVersion,
+  transition.events)` and may snapshot per the configured `SnapshotPolicy`
+  (default `everyNTransitions(50)`).
+- `matchTerminate` releases the ownership lease but does **NOT** close
+  the adapter — the same adapter typically hosts other matches in the
+  same Node process.
+
+To recover after a crash, use
+[`replayMatch(adapter, matchId, toVersion?)`](../persistence/src/replay.ts)
+to rebuild the latest snapshot at or before `toVersion`.
+
+---
+
+## Reconnection
+
+When the same `userId` rejoins a match (a new `sessionId` for an existing
+user), the handler:
+
+1. Replaces the old presence in `state.presences` with the new one.
+2. Sends a fresh, filtered `state` view to the rejoiner only — other
+   players are **not** re-broadcast to.
+3. Preserves the per-match idempotency cache, so any in-flight client
+   retries from before the disconnect resolve to their cached responses.
+
+Rejoiners are detected when either (a) the userId is already in
+`state.presences` or (b) the engine has a `PlayerState` for that
+`userId` (covers the case where the player completed a turn before
+disconnecting).
+
+---
+
+## Plugins
+
+Platform plugins are an extension hook for things that don't belong
+inside the deterministic engine: analytics, leaderboards, audit
+logging, push notifications, anti-cheat sampling, achievement
+emission, etc.
+
+```ts
+import type { NakamaPlatformPlugin } from '@table-games-engine/nakama-adapter';
+
+const analytics: NakamaPlatformPlugin = {
+  name: 'analytics',
+  async onMatchCreated(ctx) {
+    await analytics.track('match_created', { matchId: ctx.matchId });
+  },
+  async onMatchEnded(ctx, result) {
+    await analytics.track('match_ended', { matchId: ctx.matchId, winners: result.winners });
+  },
+  async onPlayerAction(ctx, input, transition) {
+    await analytics.track('action', {
+      matchId: ctx.matchId,
+      playerId: input.playerId,
+      actionTypeId: input.type === 'action' ? input.data.actionTypeId : input.type,
+      version: transition.toVersion,
+    });
+  },
+};
+
+createMatchHandler({ /* ... */, plugins: [analytics] });
+```
+
+### Plugin contract
+
+- All callbacks are **optional** — implement only what you need.
+- All callbacks are **async** and invoked **fire-and-forget** by the
+  match handler. The match loop does NOT await plugin promises.
+- Plugin failures (sync throws or rejected promises) are caught and
+  logged via `logger.error('plugin %s hook %s rejected: %s', name, hook, err)`.
+  A failing plugin **never** crashes the match.
+- Plugins are invoked in registration order, but their promises run in
+  parallel (no serialization).
+- Plugins receive a `PluginContext` (`{ matchId, gameId, state, now }`) —
+  treat `state` as readonly.
+
+### Hook coverage
+
+| Hook                 | Fires when                                                              |
+| -------------------- | ----------------------------------------------------------------------- |
+| `onMatchCreated`     | `matchInit` completes.                                                  |
+| `onMatchStarted`     | Match transitions `lobby -> active` (enough seats filled).             |
+| `onPlayerJoined`     | Each presence in a `matchJoin` (fresh joins and reconnects).            |
+| `onPlayerLeft`       | Each presence in a `matchLeave`.                                        |
+| `onPlayerAction`     | A player-driven `applyAction` transition succeeded (one per action).    |
+| `onStateTransition`  | Every successful transition (player actions, stack drain, timeouts).    |
+| `onMatchEnded`       | `checkWinConditions` reports `ended: true`.                             |
+
+---
+
+## Determinism and tests
+
+The adapter accepts an injectable `now: () => number` so tests can use a
+monotonic harness clock instead of wall-clock time. Pair it with the
+in-package harness (`__tests__/harness.ts`) and `InMemoryAdapter` from
+`@table-games-engine/persistence` to drive whole matches without Nakama:
+
+```ts
+import { createHarness } from '@table-games-engine/nakama-adapter/__tests__/harness';
+import { InMemoryAdapter, always } from '@table-games-engine/persistence';
+
+const adapter = new InMemoryAdapter(() => 0);
+const harness = createHarness();
+const handler = createMatchHandler({
+  registry, idempotencyCache, adapter,
+  now: () => harness.tick.now(),
+  policy: always(),
+});
+
+const init = handler.matchInit({}, harness.logger, {}, { gameId, matchId, playerIds: 'alice,bob' });
+// ...drive matchJoin, matchLoop, matchLeave, matchTerminate...
+```
+
+See `__tests__/e2e.test.ts` for the full pipeline exercised end-to-end.
+
+---
+
+## Public API
+
+```ts
+// Wire format
+parseInbound, serializeOutbound,
+InboundEnvelope, OutboundEnvelope,
+
+// Match handler
+createMatchHandler, NkMatchInternalState, CreateMatchHandlerOptions,
+
+// Registry
+GameRegistry, RegistryError,
+
+// Idempotency
+IdempotencyCache,
+
+// Broadcast
+broadcastViews, OPCODES,
+
+// Timeouts
+checkTimeouts, TimeoutOptions,
+
+// Persistence bridge (lower-level; createMatchHandler uses it under the hood)
+createPersistenceBridge, PersistenceBridge,
+
+// Plugins
+NakamaPlatformPlugin, PluginContext,
+invokePluginHook, dispatchPluginHook,
+```
+
+---
+
+## Status
+
+- **Phase A** — wire format, registry, idempotency, harness. Done.
+- **Phase B** — full match handler, broadcast, timeouts, signals. Done.
+- **Phase C** — persistence wiring, plugins, reconnection, e2e test,
+  this README. Done.
+
+For the normative compliance contract (what any Nakama-based adapter
+MUST guarantee, regardless of implementation), see
+[`docs/normative/platforms/nakama.md`](../../docs/normative/platforms/nakama.md).

package/dist/broadcast.d.ts

@@ -0,0 +1,27 @@
+import type { GameManifest, LegalMove, MatchState, PlayerId } from '@table-games-engine/core';
+import type { NkMatchDispatcher, NkPresence } from './types.js';
+/**
+ * Opcode allocation for the adapter.
+ *
+ *   STATE_UPDATE = 1   per-player full snapshot (`OutboundState`)
+ *   ACK          = 2   per-action acknowledgement (`OutboundAck`)
+ *   BROADCAST    = 3   broadcast events (`OutboundBroadcast`)
+ *   MATCH_ENDED  = 4   terminal `match-ended`
+ *   TRANSITION   = 5   incremental transition deltas (future use)
+ */
+export declare const OPCODES: {
+    readonly STATE_UPDATE: 1;
+    readonly ACK: 2;
+    readonly BROADCAST: 3;
+    readonly MATCH_ENDED: 4;
+    readonly TRANSITION: 5;
+};
+export type Opcode = (typeof OPCODES)[keyof typeof OPCODES];
+/**
+ * Compute and dispatch a filtered `state-update` envelope to each presence.
+ *
+ * Players whose `userId` is not registered as a `PlayerId` in `state.players`
+ * are skipped — they may be observers (Phase B doesn't model them) and we
+ * never broadcast a `PlayerView` for an unknown viewer.
+ */
+export declare function broadcastViews(state: MatchState, manifest: GameManifest, dispatcher: NkMatchDispatcher, presences: ReadonlyArray<NkPresence>, legalMovesFor?: (playerId: PlayerId) => ReadonlyArray<LegalMove>): void;

package/dist/idempotency.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Per-match idempotency cache: when a client retries a message
+ * with the same `clientId`, the adapter should replay the original outbound
+ * response instead of executing the action twice.
+ *
+ * Cache layout:
+ *   matchId -> Map<clientId, { response: OutboundEnvelope; expiresAt }>
+ *
+ * Entries expire after `ttlMs` (default 5 min). The clock is injectable for
+ * deterministic tests. Pruning runs on every `get` / `set` for the affected
+ * match — it stays cheap because each match's map is small (one entry per
+ * recent action) and we only walk one match at a time.
+ */
+import type { OutboundEnvelope } from './serialization.js';
+/** A single cache entry. */
+export interface IdempotencyEntry {
+    readonly response: OutboundEnvelope;
+    readonly expiresAt: number;
+}
+/** Constructor options for `IdempotencyCache`. */
+export interface IdempotencyCacheOptions {
+    /** Entry lifetime in milliseconds. Defaults to 5 minutes. */
+    readonly ttlMs?: number;
+    /** Clock source (ms epoch). Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+export declare class IdempotencyCache {
+    private readonly buckets;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(options?: IdempotencyCacheOptions);
+    /**
+     * Look up a cached response. Prunes expired entries for the match as a
+     * side effect, so a stale entry is never returned.
+     */
+    get(matchId: string, clientId: string): OutboundEnvelope | null;
+    /**
+     * Cache `response` under `(matchId, clientId)` with TTL. Replaces any
+     * existing entry for the same key.
+     */
+    set(matchId: string, clientId: string, response: OutboundEnvelope): void;
+    /**
+     * Drop the entire bucket for `matchId`. Use when a match terminates so
+     * we don't hold the response payloads in memory.
+     */
+    clear(matchId: string): void;
+    /**
+     * Walk every bucket and drop expired entries. Empty buckets are removed.
+     */
+    prune(): void;
+    /** Total number of live entries across all buckets. Test-only helper. */
+    get size(): number;
+    private pruneBucket;
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Public barrel for `@table-games-engine/nakama-adapter`.
+ *
+ * This package wraps the pure `EngineOperations` from `@table-games-engine/core`
+ * (and the persistence layer from `@table-games-engine/persistence`) behind a
+ * Nakama match handler so that multiple players can connect via WebSocket.
+ */
+export type { NkLogger, NkPresence, NkMatchData, NkMatchDispatcher, NkMatchState, NkMatchHandler, } from './types.js';
+export { parseInbound, serializeOutbound, } from './serialization.js';
+export type { InboundEnvelope, OutboundEnvelope, InboundAction, InboundPass, InboundConcede, InboundChooseTargets, InboundOrderTriggers, InboundAdminPause, InboundAdminResume, InboundMalformed, OutboundState, OutboundTransition, OutboundAck, OutboundBroadcast, OutboundMatchEnded, } from './serialization.js';
+export { GameRegistry, RegistryError } from './registry.js';
+export { registerPlugin } from './register-plugin.js';
+export type { RegisteredGame, RegisterArgs, GameSetup, } from './registry.js';
+export { IdempotencyCache } from './idempotency.js';
+export type { IdempotencyEntry, IdempotencyCacheOptions, } from './idempotency.js';
+export { createMatchHandler } from './match-handler.js';
+export type { MatchStatus, NkMatchInternalState, CreateMatchHandlerOptions, } from './match-handler.js';
+export { broadcastViews, OPCODES } from './broadcast.js';
+export type { Opcode } from './broadcast.js';
+export { checkTimeouts } from './timeouts.js';
+export type { TimeoutOptions } from './timeouts.js';
+export { createPersistenceBridge } from './persistence-bridge.js';
+export type { PersistenceBridge, CreatePersistenceBridgeArgs, } from './persistence-bridge.js';
+export { invokePluginHook, dispatchPluginHook, } from './plugins.js';
+export type { NakamaPlatformPlugin, PluginContext, } from './plugins.js';