@table-games-engine/persistence 0.0.0-stage → 0.1.1

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,69 @@
-# 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 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';
+
+const adapter = new SqliteAdapter('./match.db');
+
+const engine = await createPersistedEngine({
+  manifest, initialState, handlers,
+  adapter,
+  matchId: 'match-42',
+  policy: everyNTransitions(50),   // default
+  ownerNode: 'node-A',             // optional ownership lease
+  leaseSeconds: 60,                // optional, default 60
+});
+
+const r = await engine.applyAction(myInput);   // same shape as the core Engine, but async
+if (r.ok) await engine.resolveTopFrame();
+
+await engine.forceSnapshot();                  // e.g. on match end
+const recovered = await replayMatch(adapter, 'match-42');
+checksumState(recovered!) === checksumState(engine.getState());
+await engine.close();                          // releases the lease and closes the DB handle
+```
+
+## 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
+
+FSL-1.1-ALv2 (Functional Source License, converts to Apache-2.0 after two years). See `LICENSE.md` in the package.

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';