@table-games-engine/persistence 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,164 @@
-# Temporary Holding Version
+# `@table-games-engine/persistence`
 
-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.
+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.
+
+## Quick start
+
+```ts
+import {
+  SqliteAdapter,
+  createPersistedEngine,
+  everyNTransitions,
+  replayMatch,
+  checksumState,
+} from '@table-games-engine/persistence';
+import { manifest, handlers, initialState } from './my-game';
+
+const adapter = new SqliteAdapter('./match.db');
+
+const engine = await createPersistedEngine({
+  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
+});
+
+// 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();
+
+// Recover from anywhere: latest snapshot at or before a given version.
+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();
+```
+
+## 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
+```
+
+Unit tests use `InMemoryAdapter` (no I/O); the round-trip integration
+tests use `SqliteAdapter(':memory:')` for hermetic SQLite coverage.

package/dist/checksum.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Deterministic JSON checksum for `MatchState`.
+ *
+ * Algorithm:
+ *   1. Canonicalize the value to JSON with **sorted keys at every nesting
+ *      level** (arrays preserve their order; objects are reserialized with
+ *      lexicographically ordered keys).
+ *   2. Hash the canonical string with FNV-1a 32-bit (same primitive as
+ *      `core/engine/rng`).
+ *   3. Format the hash as a lowercase 8-character hex string.
+ *
+ * Two states with semantically identical content produce identical checksums
+ * regardless of how their JS object literals were constructed (key insertion
+ * order is irrelevant). The function is pure and never mutates its input.
+ */
+import type { MatchState } from '@table-games-engine/core';
+/**
+ * Compute a deterministic 8-character lowercase-hex checksum of `state`.
+ *
+ * Pure: does not mutate the input.
+ */
+export declare function checksumState(state: MatchState): string;

package/dist/core.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Nakama-safe subset of @table-games-engine/persistence: no
+ * SqliteAdapter (node:fs / better-sqlite3 are unavailable in Nakama's JS
+ * runtime). Bundlers alias '@table-games-engine/persistence' to this entry.
+ */
+export { InMemoryAdapter } from './in-memory.js';
+export { checksumState } from './checksum.js';
+export { everyNTransitions, everyTTicks, always, never, combine } from './snapshots.js';
+export type { SnapshotPolicy } from './snapshots.js';

package/dist/core.js

@@ -0,0 +1,239 @@
+// src/checksum.ts
+var FNV_OFFSET = 2166136261;
+var FNV_PRIME = 16777619;
+function fnv1a32(input) {
+  let h = FNV_OFFSET;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, FNV_PRIME);
+  }
+  return h >>> 0;
+}
+function canonicalize(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "null";
+  const t = typeof value;
+  if (t === "number") {
+    if (!Number.isFinite(value)) return "null";
+    return JSON.stringify(value);
+  }
+  if (t === "string" || t === "boolean") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map((v) => canonicalize(v)).join(",") + "]";
+  }
+  if (t === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const parts = [];
+    for (const k of keys) {
+      const v = obj[k];
+      if (v === void 0) continue;
+      parts.push(JSON.stringify(k) + ":" + canonicalize(v));
+    }
+    return "{" + parts.join(",") + "}";
+  }
+  return "null";
+}
+function checksumState(state) {
+  const canonical = canonicalize(state);
+  const h = fnv1a32(canonical);
+  return h.toString(16).padStart(8, "0");
+}
+
+// src/in-memory.ts
+var InMemoryAdapter = class {
+  matches = /* @__PURE__ */ new Map();
+  now;
+  closed = false;
+  constructor(now = () => Date.now()) {
+    this.now = now;
+  }
+  getOrCreate(matchId) {
+    let data = this.matches.get(matchId);
+    if (!data) {
+      data = {
+        snapshots: [],
+        events: [],
+        lastEventVersion: -1,
+        ownership: null
+      };
+      this.matches.set(matchId, data);
+    }
+    return data;
+  }
+  persistSnapshot(matchId, state, checksum) {
+    const data = this.getOrCreate(matchId);
+    const version = state.version;
+    const existing = data.snapshots.find((s) => s.version === version);
+    if (existing && existing.checksum !== checksum) {
+      return Promise.reject(
+        new Error(
+          `InMemoryAdapter: snapshot integrity violation for match ${String(
+            matchId
+          )} at version ${String(version)}: existing checksum ${existing.checksum} != new checksum ${checksum}`
+        )
+      );
+    }
+    if (!existing) {
+      data.snapshots.push({ version, state, checksum });
+    }
+    return Promise.resolve();
+  }
+  loadSnapshot(matchId, atVersion) {
+    const data = this.matches.get(matchId);
+    if (!data || data.snapshots.length === 0) return Promise.resolve(null);
+    let chosen = null;
+    if (atVersion === void 0) {
+      let bestIdx = -1;
+      let bestVersion = -Infinity;
+      for (let i = 0; i < data.snapshots.length; i++) {
+        const s = data.snapshots[i];
+        const v = s.version;
+        if (v >= bestVersion) {
+          bestVersion = v;
+          bestIdx = i;
+        }
+      }
+      chosen = bestIdx >= 0 ? data.snapshots[bestIdx] : null;
+    } else {
+      const target = atVersion;
+      let bestVersion = -Infinity;
+      for (const s of data.snapshots) {
+        const v = s.version;
+        if (v <= target && v >= bestVersion) {
+          bestVersion = v;
+          chosen = s;
+        }
+      }
+    }
+    if (!chosen) return Promise.resolve(null);
+    const computed = checksumState(chosen.state);
+    if (computed !== chosen.checksum) {
+      return Promise.reject(
+        new Error(
+          `InMemoryAdapter: checksum mismatch on load for match ${String(
+            matchId
+          )} at version ${String(chosen.version)}: stored ${chosen.checksum}, computed ${computed}`
+        )
+      );
+    }
+    return Promise.resolve(chosen.state);
+  }
+  appendEvents(matchId, transitionVersion, events) {
+    const data = this.getOrCreate(matchId);
+    const v = transitionVersion;
+    if (v <= data.lastEventVersion) {
+      return Promise.reject(
+        new Error(
+          `InMemoryAdapter: appendEvents version regression for match ${String(
+            matchId
+          )}: got ${v}, last was ${data.lastEventVersion}`
+        )
+      );
+    }
+    data.events.push({ version: transitionVersion, events });
+    data.lastEventVersion = v;
+    return Promise.resolve();
+  }
+  loadEvents(matchId, fromVersion, toVersion) {
+    const data = this.matches.get(matchId);
+    if (!data) return Promise.resolve([]);
+    const from = fromVersion;
+    const to = toVersion;
+    const out = [];
+    for (const batch of data.events) {
+      const v = batch.version;
+      if (v > from && v <= to) {
+        out.push(...batch.events);
+      }
+    }
+    return Promise.resolve(out);
+  }
+  acquireOwnership(matchId, ownerNode, leaseSeconds) {
+    const data = this.getOrCreate(matchId);
+    const now = this.now();
+    const current = data.ownership;
+    const expired = current === null || current.expiresAt <= now;
+    if (!expired && current.owner !== ownerNode) {
+      return Promise.resolve(false);
+    }
+    data.ownership = {
+      owner: ownerNode,
+      expiresAt: now + leaseSeconds * 1e3
+    };
+    return Promise.resolve(true);
+  }
+  releaseOwnership(matchId, ownerNode) {
+    const data = this.matches.get(matchId);
+    if (!data) return Promise.resolve();
+    if (data.ownership && data.ownership.owner === ownerNode) {
+      data.ownership = null;
+    }
+    return Promise.resolve();
+  }
+  close() {
+    this.closed = true;
+    void this.closed;
+    return Promise.resolve();
+  }
+};
+
+// src/snapshots.ts
+function everyNTransitions(n) {
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(
+      `everyNTransitions: n must be a positive integer (got ${String(n)})`
+    );
+  }
+  return {
+    shouldSnapshot(_state, sinceLast) {
+      return sinceLast.transitionsSince >= n;
+    }
+  };
+}
+function everyTTicks(t) {
+  if (!Number.isInteger(t) || t < 1) {
+    throw new Error(
+      `everyTTicks: t must be a positive integer (got ${String(t)})`
+    );
+  }
+  return {
+    shouldSnapshot(_state, sinceLast) {
+      return sinceLast.ticksSince >= t;
+    }
+  };
+}
+function always() {
+  return {
+    shouldSnapshot() {
+      return true;
+    }
+  };
+}
+function never() {
+  return {
+    shouldSnapshot() {
+      return false;
+    }
+  };
+}
+function combine(...policies) {
+  if (policies.length === 0) return never();
+  return {
+    shouldSnapshot(state, sinceLast) {
+      for (const p of policies) {
+        if (p.shouldSnapshot(state, sinceLast)) return true;
+      }
+      return false;
+    }
+  };
+}
+export {
+  InMemoryAdapter,
+  always,
+  checksumState,
+  combine,
+  everyNTransitions,
+  everyTTicks,
+  never
+};

package/dist/in-memory.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview In-memory `EngineAdapter` reference implementation.
+ *
+ * Stores all data in JS data structures (no I/O). Useful as a reference
+ * implementation, for tests, and for ephemeral sandbox runs. Persistence
+ * across process restarts requires a real backend (e.g. SQLite — Phase B).
+ */
+import type { EngineAdapter, MatchId, MatchState, StateVersion, GameEvent, ImmutableList } from '@table-games-engine/core';
+/**
+ * In-memory `EngineAdapter`. Methods resolve immediately via `Promise.resolve`;
+ * no I/O is performed.
+ *
+ * Accepts an optional `now` function for deterministic lease testing.
+ */
+export declare class InMemoryAdapter implements EngineAdapter {
+    private readonly matches;
+    private readonly now;
+    private closed;
+    constructor(now?: () => number);
+    private getOrCreate;
+    persistSnapshot(matchId: MatchId, state: MatchState, checksum: string): Promise<void>;
+    loadSnapshot(matchId: MatchId, atVersion?: StateVersion): Promise<MatchState | null>;
+    appendEvents(matchId: MatchId, transitionVersion: StateVersion, events: ImmutableList<GameEvent>): Promise<void>;
+    loadEvents(matchId: MatchId, fromVersion: StateVersion, toVersion: StateVersion): Promise<ImmutableList<GameEvent>>;
+    acquireOwnership(matchId: MatchId, ownerNode: string, leaseSeconds: number): Promise<boolean>;
+    releaseOwnership(matchId: MatchId, ownerNode: string): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Public barrel for `@table-games-engine/persistence`.
+ */
+export { InMemoryAdapter } from './in-memory.js';
+export { checksumState } from './checksum.js';
+export { SqliteAdapter } from './sqlite/adapter.js';
+export type { SqliteAdapterOptions } from './sqlite/adapter.js';
+export { replayMatch, loadEventsBetween } from './replay.js';
+export { everyNTransitions, everyTTicks, always, never, combine, } from './snapshots.js';
+export type { SnapshotPolicy } from './snapshots.js';
+export { createPersistedEngine } from './persisted-engine.js';
+export type { PersistedEngine } from './persisted-engine.js';