@table-games-engine/persistence 0.1.0 → 0.1.1

package/README.md

@@ -1,164 +1,69 @@
-# `@table-games-engine/persistence`
-
-Persistence layer for the table-games engine. Implements the
-`EngineAdapter` contract from `@table-games-engine/core` and provides
-helpers for snapshotting, replay, and ownership leasing.
-
-This package is internal to the workspace (`"private": true`) and is
-imported by the runtime, the Nakama adapter (M3), and any host that
-needs to keep matches alive across restarts.
-
-## What lives here
-
-- **`InMemoryAdapter`** — reference adapter, no I/O. Used in tests and
-  for ephemeral sandbox runs.
-- **`SqliteAdapter`** — SQLite-backed adapter via `better-sqlite3`.
-  Construct with a filesystem path or `':memory:'`. Migrations are
-  applied eagerly.
-- **`checksumState`** — deterministic JSON-canonical FNV-1a 32-bit
-  checksum of a `MatchState`. Used by both adapters and by callers
-  that want to verify replayed state.
-- **`createPersistedEngine`** — wraps an in-process `Engine` so every
-  transition is mirrored into the adapter (events appended, snapshots
-  taken per policy).
-- **Snapshot policies** — `everyNTransitions`, `everyTTicks`, `always`,
-  `never`, `combine`.
-- **`replayMatch` / `loadEventsBetween`** — reconstruction helpers.
+# @table-games-engine/persistence
+
+Persistence for table-games-engine matches: event and snapshot storage (in-memory or SQLite), snapshot policies, state checksums, replay, and ownership leases.
+
+Most game authors don't install this directly: it comes with [`@table-games-engine/game-kit`](https://www.npmjs.com/package/@table-games-engine/game-kit) and is used by [`@table-games-engine/nakama-adapter`](https://www.npmjs.com/package/@table-games-engine/nakama-adapter). Install it to keep matches alive across restarts on your own host.
+
+## Install
+
+```sh
+npm install @table-games-engine/persistence
+```
+
+`SqliteAdapter` uses `better-sqlite3` (a native module, installed as a dependency).
+
+## What is in it
+
+- `InMemoryAdapter` - no I/O, for tests and ephemeral runs.
+- `SqliteAdapter(path, opts?)` - SQLite via `better-sqlite3`; takes a file path or `':memory:'`; WAL mode, migrations applied on open.
+- `createPersistedEngine(args)` - wraps a core `Engine` so every transition appends events and snapshots per policy.
+- `checksumState(state)` - deterministic checksum of a `MatchState` (FNV-1a 32-bit over canonical JSON).
+- `replayMatch(adapter, matchId, toVersion?)` and `loadEventsBetween(adapter, matchId, from, to)`.
+- Snapshot policies: `everyNTransitions`, `everyTTicks`, `always`, `never`, `combine`.
 
 ## Quick start
 
 ```ts
-import {
-  SqliteAdapter,
-  createPersistedEngine,
-  everyNTransitions,
-  replayMatch,
-  checksumState,
-} from '@table-games-engine/persistence';
-import { manifest, handlers, initialState } from './my-game';
+import { SqliteAdapter, createPersistedEngine, everyNTransitions, replayMatch, checksumState } from '@table-games-engine/persistence';
 
 const adapter = new SqliteAdapter('./match.db');
 
 const engine = await createPersistedEngine({
-  manifest,
-  initialState,
-  handlers,
+  manifest, initialState, handlers,
   adapter,
   matchId: 'match-42',
-  policy: everyNTransitions(50), // default, shown for clarity
-  ownerNode: 'node-A',           // optional ownership lease
-  leaseSeconds: 60,              // optional, defaults to 60
+  policy: everyNTransitions(50),   // default
+  ownerNode: 'node-A',             // optional ownership lease
+  leaseSeconds: 60,                // optional, default 60
 });
 
-// Drive the game. Each call returns a Promise<Result<...>>.
-const r = await engine.applyAction(myInput);
-if (r.ok) {
-  await engine.resolveTopFrame();
-}
-
-// Optional: force a snapshot at the current state (e.g. on match end).
-await engine.forceSnapshot();
+const r = await engine.applyAction(myInput);   // same shape as the core Engine, but async
+if (r.ok) await engine.resolveTopFrame();
 
-// Recover from anywhere: latest snapshot at or before a given version.
+await engine.forceSnapshot();                  // e.g. on match end
 const recovered = await replayMatch(adapter, 'match-42');
-
-// Verify integrity (the adapter does this on load, but you may want
-// to assert it matches the live engine before swapping).
 checksumState(recovered!) === checksumState(engine.getState());
-
-// Release the lease and close the DB handle.
-await engine.close();
+await engine.close();                          // releases the lease and closes the DB handle
 ```
 
-## Snapshot cadence
-
-The persisted engine is policy-driven; pass `policy` when you construct
-it. Built-in policies:
-
-| Policy                     | When it fires                          |
-| -------------------------- | -------------------------------------- |
-| `everyNTransitions(n)`     | After every `n` engine transitions     |
-| `everyTTicks(t)`           | After every `t` logical ticks          |
-| `always()`                 | Every transition (deterministic tests) |
-| `never()`                  | Never (benchmarks, audit-only engines) |
-| `combine(...policies)`     | If any sub-policy returns true         |
-
-Default is `everyNTransitions(50)`, matching the M2 plan's "snapshot
-every ~50 transitions" guidance.
-
-### Cadence trade-offs
-
-- **Frequent snapshots** (low N): faster recovery, smaller replay
-  windows, but more bytes written per second and higher checksum cost.
-- **Sparse snapshots** (high N): cheaper writes, but larger windows
-  between recoverable points. With M2's design, you can only recover
-  to versions that were snapshotted (see "Replay contract" below).
-- **`always()`** is the right default for **async-mode** games (every
-  action persists; players may be offline for hours/days) and for
-  tests that want deterministic post-conditions.
-- **`combine(everyNTransitions(50), everyTTicks(60))`** mirrors the
-  M2 plan's "every N transitions OR every T seconds" hybrid.
-
-## Replay contract (M2 design)
-
-`replayMatch(adapter, matchId, toVersion?)` returns the **latest
-snapshot whose `state.version` is `<= toVersion`**, or the absolute
-latest snapshot when `toVersion` is omitted, or `null` when nothing has
-been persisted.
-
-It does **not** replay events onto state. This is a deliberate M2
-decision:
-
-- The adapter stores **snapshots** (full state) and **events**
-  (game-domain events for triggers, audit, spectator catch-up).
-- Events are NOT a derivation of `StateMutation`s. We cannot
-  reconstruct state at an arbitrary version V by "applying events" —
-  there is no such operation defined.
-- To recover to an exact version V, configure a snapshot policy that
-  guarantees a snapshot at V (e.g. `always()` or a turn-aligned
-  cadence).
-- For audit, use `loadEventsBetween(adapter, matchId, from, to)` to
-  fetch the half-open `(from, to]` slice of the event log.
-
-M3 (Nakama adapter) will revisit this if cross-node failover requires
-sub-snapshot precision. For now, snapshot density is the knob.
-
-## Sync/async boundary
-
-The core `Engine` API is **synchronous**: `applyAction(input): Result<...>`.
-The persisted wrapper exposes the same shape but each transition method
-returns a `Promise<Result<...>>` because adapter writes are async.
-
-Adapter failures (e.g. SQLite I/O error, network error in a future
-remote adapter) **propagate to the caller as a rejected Promise**.
-They do **not** roll back the in-memory state — by the time the adapter
-write happens, the engine has already produced and applied the
-transition. Callers that need all-or-nothing semantics must layer their
-own retry / quarantine on top, or close the engine and recover from the
-last good snapshot.
-
-## Ownership
-
-If you pass `ownerNode` to `createPersistedEngine`, the wrapper
-acquires an exclusive lease on `matchId` before doing anything else.
-Construction throws if another node holds a non-expired lease.
-
-Leases auto-expire after `leaseSeconds` seconds. Use `engine.close()`
-or `engine.releaseOwnership()` to release explicitly.
-
-## Determinism guarantees
-
-- The wrapper's behaviour matches the unwrapped `createEngine` exactly
-  for game logic. Tests assert byte-for-byte state equality.
-- Checksums are deterministic across machines and processes.
-- `SqliteAdapter` uses WAL mode and per-call transactions for atomic
-  writes.
-
-## Testing
-
-```bash
-npm test --workspace=@table-games-engine/persistence
-```
+## Snapshot policies
+
+| Policy | Fires |
+|---|---|
+| `everyNTransitions(n)` | after every `n` transitions |
+| `everyTTicks(t)` | after every `t` logical ticks |
+| `always()` | every transition (best for async games and deterministic tests) |
+| `never()` | never |
+| `combine(...policies)` | when any sub-policy fires |
+
+## Replay
+
+`replayMatch` returns the latest snapshot at or before `toVersion` (or the latest overall), or `null` if nothing was stored. It does not re-apply events, so to recover an exact version use a policy that snapshots there (for example `always()`). Use `loadEventsBetween` for the audit log.
+
+## Failure behaviour
+
+Adapter errors reject the returned promise and do not roll back in-memory state. If you need all-or-nothing, close the engine and recover from the last good snapshot. With `ownerNode` set, construction throws if another node holds an unexpired lease.
+
+## Licence
 
-Unit tests use `InMemoryAdapter` (no I/O); the round-trip integration
-tests use `SqliteAdapter(':memory:')` for hermetic SQLite coverage.
+FSL-1.1-ALv2 (Functional Source License, converts to Apache-2.0 after two years). See `LICENSE.md` in the package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@table-games-engine/persistence",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "publishConfig": {
     "access": "public"
   },
@@ -26,7 +26,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@table-games-engine/core": "^0.1.0",
+    "@table-games-engine/core": "^0.1.1",
     "better-sqlite3": "^11.0.0"
   },
   "devDependencies": {
@@ -34,5 +34,15 @@
     "typescript": "^5.4.0",
     "vitest": "^2.0.0"
   },
-  "license": "FSL-1.1-ALv2"
+  "license": "FSL-1.1-ALv2",
+  "description": "Snapshot, event and replay persistence (in-memory and SQLite) for table-games-engine matches.",
+  "keywords": [
+    "table-games",
+    "turn-based",
+    "multiplayer",
+    "game-engine",
+    "nakama",
+    "boardgame"
+  ],
+  "homepage": "https://www.npmjs.com/package/@table-games-engine/persistence"
 }