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

package/dist/persisted-engine.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview `PersistedEngine` — `Engine` + adapter writes.
+ *
+ * Wraps an in-process `Engine` (from `@table-games-engine/core`) so that every
+ * transition-producing call ALSO:
+ *   1. Appends the transition's events to the adapter's event log
+ *      (audit trail / triggers / spectator catch-up).
+ *   2. Asks the configured `SnapshotPolicy` whether to snapshot, and if
+ *      so writes the new `MatchState` (with checksum) to the adapter.
+ *
+ * # Sync vs async boundary
+ *
+ * The core `Engine` API is **synchronous**: `applyAction(input): Result<...>`
+ * returns immediately. The persisted wrapper exposes the same shape but
+ * each method returns a `Promise<Result<...>>` because adapter writes are
+ * async. Internally:
+ *   1. The underlying engine call runs synchronously and updates the
+ *      in-memory state. (This is the source of truth — the wrapper does
+ *      NOT undo it on adapter failure.)
+ *   2. The adapter writes are awaited.
+ *   3. Adapter errors propagate to the caller via the returned Promise.
+ *      They do NOT roll back the in-memory state. Document this clearly:
+ *      callers that require all-or-nothing semantics must layer their own
+ *      retry/quarantine logic above the wrapper, or close the engine and
+ *      restart from the last good snapshot.
+ *
+ * The trade-off is intentional. The alternative (rollback the in-memory
+ * state on failure) would require synthesising an inverse transition or
+ * snapshotting before each call, both of which are noticeably more
+ * expensive than letting the host runtime decide what to do on failure.
+ *
+ * # Ownership
+ *
+ * If `ownerNode` is provided to {@link createPersistedEngine}, the wrapper
+ * acquires an ownership lease on `matchId` before doing anything else.
+ * On failure (another node holds a non-expired lease) the factory throws.
+ * `release()` releases the lease; `close()` releases AND closes the
+ * adapter handle.
+ *
+ * # Initial snapshot
+ *
+ * The wrapper unconditionally persists the initial state as snapshot v0.
+ * This guarantees `replayMatch` returns a valid state even if zero
+ * transitions occur before a crash, and gives the snapshot policy a
+ * concrete "since-last" baseline to count from.
+ */
+import type { ActionHandler, EngineAdapter, GameEndCheck, GameManifest, MatchId, MatchState, ResolutionFailure, Result, StateTransition } from '@table-games-engine/core';
+import type { ActionInput, ActionValidationResult } from '@table-games-engine/core';
+import { type SnapshotPolicy } from './snapshots.js';
+/**
+ * Arguments for {@link createPersistedEngine}.
+ */
+export interface CreatePersistedEngineArgs {
+    /** Game manifest passed straight through to {@link createEngine}. */
+    readonly manifest: GameManifest;
+    /** Initial state (will be persisted as snapshot v0). */
+    readonly initialState: MatchState;
+    /** Action handlers passed straight through to {@link createEngine}. */
+    readonly handlers: Record<string, ActionHandler>;
+    /** Persistence backend. The wrapper does NOT take ownership of close(). */
+    readonly adapter: EngineAdapter;
+    /** Match ID used for snapshot/event/ownership scoping. */
+    readonly matchId: MatchId;
+    /** Snapshot cadence; defaults to `everyNTransitions(50)` per the M2 plan. */
+    readonly policy?: SnapshotPolicy;
+    /**
+     * If provided, the wrapper acquires an ownership lease on `matchId` for
+     * `ownerNode` during construction. Construction throws if the lease
+     * cannot be acquired (another node owns it).
+     */
+    readonly ownerNode?: string;
+    /** Lease duration in seconds. Defaults to 60. */
+    readonly leaseSeconds?: number;
+}
+/**
+ * Persisted engine handle.
+ *
+ * Mirrors the shape of `Engine` but every transition method is async (because
+ * adapter writes are async) and returns a `Promise<Result<...>>`. Adds
+ * lifecycle methods for ownership and snapshot control.
+ */
+export interface PersistedEngine {
+    /** Synchronous read of the current `MatchState`. */
+    getState(): MatchState;
+    /** Match ID this wrapper is bound to. */
+    getMatchId(): MatchId;
+    /**
+     * Apply a player action and persist the resulting transition.
+     *
+     * On success: in-memory state is updated, events are appended, and a
+     * snapshot is taken if the policy fires.
+     *
+     * On engine validation failure: no adapter writes occur — the engine
+     * never produced a transition.
+     *
+     * On adapter failure: the in-memory state retains the new value (the
+     * engine has already applied it). The promise rejects with the adapter
+     * error. See module doc for rationale.
+     */
+    applyAction(input: ActionInput): Promise<Result<StateTransition, ActionValidationResult>>;
+    resolveTopFrame(): Promise<Result<StateTransition, ResolutionFailure>>;
+    processTriggers(): Promise<Result<StateTransition, never>>;
+    checkStateBasedActions(): Promise<Result<StateTransition, never>>;
+    advancePhase(): Promise<Result<StateTransition, 'CANNOT_ADVANCE'>>;
+    advanceTurn(): Promise<Result<StateTransition, 'CANNOT_ADVANCE'>>;
+    /** Synchronous (the engine helper is sync and produces no transition). */
+    checkWinConditions(): GameEndCheck;
+    /**
+     * Force a snapshot at the current state, regardless of the policy.
+     *
+     * Useful for "checkpoint before risky operation", "snapshot on match
+     * end", or test determinism.
+     */
+    forceSnapshot(): Promise<void>;
+    /** Release the ownership lease (if any). Idempotent. */
+    releaseOwnership(): Promise<void>;
+    /**
+     * Release ownership AND close the underlying adapter. Idempotent for
+     * ownership; the adapter close behaviour is whatever the adapter
+     * documents (better-sqlite3 tolerates double-close).
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create a persisted engine wrapper.
+ *
+ * Steps performed during construction (in order):
+ *   1. Acquire ownership lease (if `ownerNode` provided). Throws on failure.
+ *   2. Persist `initialState` as the v0 snapshot.
+ *   3. Initialise the in-memory `Engine` and return the wrapper.
+ *
+ * The default policy is `everyNTransitions(50)` per the M2 plan. Tests that
+ * want deterministic snapshot frequency should pass `always()` or `never()`.
+ */
+export declare function createPersistedEngine(args: CreatePersistedEngineArgs): Promise<PersistedEngine>;

package/dist/replay.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Replay helper for `EngineAdapter`.
+ *
+ * # Replay contract (M2 design)
+ *
+ * The adapter stores TWO independent streams per match:
+ *   - **Snapshots** — full `MatchState` blobs at specific versions.
+ *   - **Events** — `GameEvent` records for triggers / audit / spectator
+ *     catch-up.
+ *
+ * Crucially, events are NOT a derivation of `StateMutation`s — they are
+ * the game-domain things that happened (e.g. `damage-dealt`, `card-drawn`).
+ * That means we cannot reconstruct state by "replaying events" the way
+ * an event-sourced system might. To rebuild state at version V we have
+ * two options:
+ *
+ *   1. Load a snapshot whose version is `<= V`, and either accept its
+ *      version (if there is no snapshot at exactly V) or re-execute the
+ *      original action handlers from that snapshot up to V.
+ *   2. Persist a snapshot at every version (snapshot policy
+ *      `always()`), which collapses (1) to "load the snapshot at V".
+ *
+ * In M2 we deliberately choose the simpler design: `replayMatch` returns
+ * the **latest snapshot at or before `toVersion`**. Callers control
+ * snapshot cadence via `SnapshotPolicy` (see `./snapshots.ts`); if a
+ * caller needs to recover to an exact version V, they should configure
+ * a policy that snapshots at V (e.g. `always()` or a turn-aligned
+ * cadence).
+ *
+ * Re-executing handlers between two snapshots to land on an arbitrary
+ * intermediate version is intentionally out of scope for M2. M3
+ * (Nakama adapter) will revisit this if cross-node failover requires
+ * sub-snapshot precision; for now, snapshot density is the knob.
+ *
+ * `loadEventsBetween` is a thin sugar wrapper around
+ * `EngineAdapter.loadEvents` for callers that want the audit trail
+ * across a version range.
+ */
+import type { EngineAdapter, MatchId, MatchState, StateVersion, GameEvent, ImmutableList } from '@table-games-engine/core';
+/**
+ * Reconstruct the recorded `MatchState` for `matchId` at or before
+ * `toVersion`.
+ *
+ * Returns the latest snapshot whose `state.version` is `<= toVersion`,
+ * or the absolute latest snapshot when `toVersion` is omitted, or
+ * `null` when no snapshot has been persisted for the match.
+ *
+ * The returned state is the exact value that was passed to
+ * `persistSnapshot` at the time of capture (modulo JSON round-trip,
+ * which `MatchState` is designed to survive).
+ *
+ * Pure with respect to the caller: makes no engine calls, only adapter
+ * reads. The integrity check (checksum verification) happens inside
+ * `loadSnapshot` per the adapter contract.
+ */
+export declare function replayMatch(adapter: EngineAdapter, matchId: MatchId, toVersion?: StateVersion): Promise<MatchState | null>;
+/**
+ * Load events recorded in the half-open interval `(fromVersion, toVersion]`.
+ *
+ * Convenience alias for `EngineAdapter.loadEvents`; exposed from the
+ * replay module so callers that import "replay-related" helpers find it
+ * alongside `replayMatch`.
+ */
+export declare function loadEventsBetween(adapter: EngineAdapter, matchId: MatchId, fromVersion: StateVersion, toVersion: StateVersion): Promise<ImmutableList<GameEvent>>;

package/dist/snapshots.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview Snapshot cadence policies for the persisted engine.
+ *
+ * A `SnapshotPolicy` decides — given the current `MatchState` and a count of
+ * "things since the last snapshot" — whether the engine should snapshot
+ * RIGHT NOW. Policies are stateless predicates; the persisted engine is
+ * responsible for tracking `transitionsSince` and `ticksSince`.
+ *
+ * Policies are pluggable and composable: real deployments will combine a
+ * "every N transitions" rule with a "every T seconds of logical tick" rule
+ * via {@link combine}, while tests use {@link always} (snapshot every step)
+ * or {@link never} (snapshot never).
+ *
+ * # Why a separate "since-last" counter?
+ *
+ * `MatchState.version` could be inspected directly, but the wrapper does
+ * NOT have access to the version of the previous snapshot in a stateless
+ * predicate. We keep the policy pure and let the wrapper own the counters.
+ * This keeps the policy a single-line decision and makes `combine` trivial.
+ *
+ * # Defaults
+ *
+ * The persisted engine wrapper defaults to `everyNTransitions(50)` when
+ * the caller does not supply a policy — chosen to align with the M2 plan
+ * "snapshot every ~50 transitions" guidance.
+ */
+import type { MatchState } from '@table-games-engine/core';
+/**
+ * A snapshot cadence policy.
+ *
+ * `shouldSnapshot` is invoked AFTER each engine transition. It receives:
+ *   - `state`: the current `MatchState` AFTER the transition.
+ *   - `sinceLast`: counters tracked by the wrapper since the last
+ *     snapshot was taken. `transitionsSince` and `ticksSince` are both
+ *     `0` immediately after a snapshot fires.
+ *
+ * Implementations MUST be pure — same arguments produce same answer.
+ */
+export interface SnapshotPolicy {
+    shouldSnapshot(state: MatchState, sinceLast: {
+        transitionsSince: number;
+        ticksSince: number;
+    }): boolean;
+}
+/**
+ * Snapshot once every `n` transitions (`n >= 1`).
+ *
+ * `n=1` is equivalent to {@link always}. `n=0` would never trigger and is
+ * disallowed — use {@link never} explicitly when you mean "off".
+ */
+export declare function everyNTransitions(n: number): SnapshotPolicy;
+/**
+ * Snapshot once every `t` logical ticks (`t >= 1`).
+ *
+ * Useful when "transitions" is too granular (e.g. lots of trigger
+ * processing per logical tick). `ticksSince` is the engine's logical
+ * `state.tick`, NOT wall-clock time.
+ */
+export declare function everyTTicks(t: number): SnapshotPolicy;
+/**
+ * Snapshot every transition. Equivalent to `everyNTransitions(1)`.
+ *
+ * Recommended for tests (round-trip determinism) and for async-mode
+ * games where every action persists.
+ */
+export declare function always(): SnapshotPolicy;
+/**
+ * Never snapshot. Useful for benchmarking the engine without persistence
+ * overhead, or for read-only "audit" engines that only need the event log.
+ */
+export declare function never(): SnapshotPolicy;
+/**
+ * Disjunction of policies: snapshot if **any** sub-policy returns `true`.
+ *
+ * Empty input returns a policy equivalent to {@link never}.
+ *
+ * The first policy that returns `true` short-circuits evaluation, so cheap
+ * predicates should come first.
+ */
+export declare function combine(...policies: SnapshotPolicy[]): SnapshotPolicy;

package/dist/sqlite/adapter.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview SQLite-backed `EngineAdapter` implementation.
+ *
+ * Uses `better-sqlite3` (synchronous, native bindings). Each `EngineAdapter`
+ * method wraps its work in `Promise.resolve(...)` to satisfy the async
+ * contract — but no real async I/O is performed.
+ *
+ * Multi-row writes (event batches, ownership upserts, snapshot inserts) are
+ * wrapped in transactions for atomicity. Snapshots and loads run integrity
+ * checks via `checksumState`.
+ *
+ * NODE-ONLY: This module imports `better-sqlite3` and `node:fs` (via
+ * `migrations.ts`). It MUST NOT be imported from `@table-games-engine/core`.
+ */
+import type { EngineAdapter, GameEvent, ImmutableList, MatchId, MatchState, StateVersion } from '@table-games-engine/core';
+export interface SqliteAdapterOptions {
+    /** Injectable clock for deterministic lease tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * SQLite-backed `EngineAdapter`.
+ *
+ * Construct with a filesystem path or `':memory:'`. Migrations are applied
+ * eagerly; the database handle is owned by this adapter and released by
+ * `close()`.
+ */
+export declare class SqliteAdapter implements EngineAdapter {
+    private readonly db;
+    private readonly now;
+    private readonly stmtInsertSnapshot;
+    private readonly stmtSelectSnapshotChecksum;
+    private readonly stmtSelectLatestSnapshot;
+    private readonly stmtSelectSnapshotAtVersion;
+    private readonly stmtMaxEventVersion;
+    private readonly stmtInsertEvent;
+    private readonly stmtSelectEvents;
+    private readonly stmtSelectOwnership;
+    private readonly stmtUpsertOwnership;
+    private readonly stmtDeleteOwnership;
+    constructor(path: string, opts?: SqliteAdapterOptions);
+    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 the underlying database. Subsequent calls into adapter methods will
+     * throw with the better-sqlite3 native error ("The database connection is
+     * not open"); we do not wrap that to keep the contract minimal.
+     *
+     * Idempotent: calling `close()` twice is a no-op (better-sqlite3 tolerates
+     * the second close cleanly when the handle is already released).
+     */
+    close(): Promise<void>;
+}

package/dist/sqlite/migrations.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview SQLite migrations for the persistence package.
+ *
+ * `applyMigrations` reads the colocated `schema.sql` at runtime and applies
+ * its DDL inside a single transaction. Idempotent: every statement uses
+ * IF NOT EXISTS, so re-running on a populated database is safe.
+ *
+ * The `_meta` table tracks `schema_version` for future migrations. Initial
+ * version is `1`. Schema-version helpers (`getSchemaVersion`,
+ * `setSchemaVersion`) are exported for forward compatibility.
+ *
+ * NOTE: This file is Node-only — it uses `fs.readFileSync` and the
+ * `better-sqlite3` Database type. It MUST NOT be imported from
+ * `@table-games-engine/core`.
+ */
+import type Database from 'better-sqlite3';
+/** Initial schema version — bump only when adding migrations. */
+export declare const CURRENT_SCHEMA_VERSION = 1;
+/**
+ * Apply the SQL schema to `db`. Idempotent: safe to run on every adapter
+ * construction.
+ */
+export declare function applyMigrations(db: Database.Database): void;
+/**
+ * Read the persisted schema version. Returns `0` when no version is recorded
+ * yet — including the case where the `_meta` table itself does not exist
+ * (i.e. brand-new database before `applyMigrations`).
+ */
+export declare function getSchemaVersion(db: Database.Database): number;
+/** Persist the schema version (used by `applyMigrations` and future runners). */
+export declare function setSchemaVersion(db: Database.Database, n: number): void;

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@table-games-engine/persistence",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "default": "./dist/core.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts src/core.ts --bundle --format=esm --platform=node --packages=external --outdir=dist && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@table-games-engine/core": "^0.1.1",
+    "better-sqlite3": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "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"
+}