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

package/dist/index.js

@@ -0,0 +1,1224 @@
+// src/serialization.ts
+var INBOUND_KINDS = /* @__PURE__ */ new Set([
+  "action",
+  "pass",
+  "concede",
+  "choose-targets",
+  "order-triggers",
+  "admin-pause",
+  "admin-resume"
+]);
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isString(v) {
+  return typeof v === "string";
+}
+function isNumber(v) {
+  return typeof v === "number" && Number.isFinite(v);
+}
+function parseInbound(json) {
+  let raw;
+  try {
+    raw = JSON.parse(json);
+  } catch (e) {
+    return {
+      kind: "malformed",
+      reason: "invalid-json",
+      detail: e instanceof Error ? e.message : String(e)
+    };
+  }
+  if (!isObject(raw)) {
+    return { kind: "malformed", reason: "not-object" };
+  }
+  const kind = raw["kind"];
+  if (!isString(kind)) {
+    return { kind: "malformed", reason: "missing-kind" };
+  }
+  if (!INBOUND_KINDS.has(kind)) {
+    return { kind: "malformed", reason: "unknown-kind", detail: kind };
+  }
+  switch (kind) {
+    case "action":
+      return parseActionEnvelope(raw);
+    case "pass":
+      return parseSimpleVersionedEnvelope(raw, "pass");
+    case "concede":
+      return parseSimpleVersionedEnvelope(raw, "concede");
+    case "choose-targets":
+      return parseChooseTargetsEnvelope(raw);
+    case "order-triggers":
+      return parseOrderTriggersEnvelope(raw);
+    case "admin-pause":
+      return parseAdminPauseEnvelope(raw);
+    case "admin-resume":
+      return parseAdminResumeEnvelope(raw);
+    default:
+      return { kind: "malformed", reason: "unknown-kind", detail: kind };
+  }
+}
+function parseActionEnvelope(raw) {
+  const clientId = raw["clientId"];
+  const stateVersion = raw["stateVersion"];
+  const action = raw["action"];
+  if (!isString(clientId) || clientId.length === 0) {
+    return { kind: "malformed", reason: "invalid-fields", detail: "clientId" };
+  }
+  if (!isNumber(stateVersion)) {
+    return {
+      kind: "malformed",
+      reason: "invalid-fields",
+      detail: "stateVersion"
+    };
+  }
+  if (!isObject(action) || action["type"] !== "action") {
+    return { kind: "malformed", reason: "invalid-fields", detail: "action" };
+  }
+  if (!isString(action["actionTypeId"])) {
+    return {
+      kind: "malformed",
+      reason: "invalid-fields",
+      detail: "action.actionTypeId"
+    };
+  }
+  return {
+    kind: "action",
+    clientId,
+    stateVersion,
+    action
+  };
+}
+function parseSimpleVersionedEnvelope(raw, kind) {
+  const clientId = raw["clientId"];
+  const stateVersion = raw["stateVersion"];
+  if (!isString(clientId) || clientId.length === 0) {
+    return { kind: "malformed", reason: "invalid-fields", detail: "clientId" };
+  }
+  if (!isNumber(stateVersion)) {
+    return {
+      kind: "malformed",
+      reason: "invalid-fields",
+      detail: "stateVersion"
+    };
+  }
+  return { kind, clientId, stateVersion };
+}
+function parseChooseTargetsEnvelope(raw) {
+  const clientId = raw["clientId"];
+  const stateVersion = raw["stateVersion"];
+  const action = raw["action"];
+  if (!isString(clientId) || clientId.length === 0) {
+    return { kind: "malformed", reason: "invalid-fields", detail: "clientId" };
+  }
+  if (!isNumber(stateVersion)) {
+    return {
+      kind: "malformed",
+      reason: "invalid-fields",
+      detail: "stateVersion"
+    };
+  }
+  if (!isObject(action) || action["type"] !== "choose_targets") {
+    return { kind: "malformed", reason: "invalid-fields", detail: "action" };
+  }
+  return {
+    kind: "choose-targets",
+    clientId,
+    stateVersion,
+    action
+  };
+}
+function parseOrderTriggersEnvelope(raw) {
+  const clientId = raw["clientId"];
+  const stateVersion = raw["stateVersion"];
+  const action = raw["action"];
+  if (!isString(clientId) || clientId.length === 0) {
+    return { kind: "malformed", reason: "invalid-fields", detail: "clientId" };
+  }
+  if (!isNumber(stateVersion)) {
+    return {
+      kind: "malformed",
+      reason: "invalid-fields",
+      detail: "stateVersion"
+    };
+  }
+  if (!isObject(action) || action["type"] !== "order_triggers") {
+    return { kind: "malformed", reason: "invalid-fields", detail: "action" };
+  }
+  return {
+    kind: "order-triggers",
+    clientId,
+    stateVersion,
+    action
+  };
+}
+function parseAdminPauseEnvelope(raw) {
+  const clientId = raw["clientId"];
+  if (!isString(clientId) || clientId.length === 0) {
+    return { kind: "malformed", reason: "invalid-fields", detail: "clientId" };
+  }
+  const reason = raw["reason"];
+  if (reason !== void 0 && !isString(reason)) {
+    return { kind: "malformed", reason: "invalid-fields", detail: "reason" };
+  }
+  return reason === void 0 ? { kind: "admin-pause", clientId } : { kind: "admin-pause", clientId, reason };
+}
+function parseAdminResumeEnvelope(raw) {
+  const clientId = raw["clientId"];
+  if (!isString(clientId) || clientId.length === 0) {
+    return { kind: "malformed", reason: "invalid-fields", detail: "clientId" };
+  }
+  return { kind: "admin-resume", clientId };
+}
+function serializeOutbound(env) {
+  return JSON.stringify(env);
+}
+
+// src/registry.ts
+var RegistryError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "RegistryError";
+    this.code = code;
+  }
+};
+var GameRegistry = class {
+  entries;
+  constructor() {
+    this.entries = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register a game. Throws `RegistryError('duplicate')` if `gameId` is
+   * already registered.
+   */
+  register(args) {
+    const key = args.gameId;
+    if (this.entries.has(key)) {
+      throw new RegistryError(
+        "duplicate",
+        `game already registered: ${key}`
+      );
+    }
+    const entry = {
+      gameId: args.gameId,
+      manifest: args.manifest,
+      handlers: { ...args.handlers },
+      setup: args.setup,
+      ...args.winChecker !== void 0 ? { winChecker: args.winChecker } : {},
+      ...args.stateBasedActions !== void 0 ? { stateBasedActions: args.stateBasedActions } : {},
+      ...args.legalMoves !== void 0 ? { legalMoves: args.legalMoves } : {}
+    };
+    this.entries.set(key, entry);
+    return entry;
+  }
+  /**
+   * Look up a registered game. Returns `null` (not undefined) when not
+   * found, to make call sites read more naturally.
+   */
+  resolve(gameId) {
+    const key = gameId;
+    return this.entries.get(key) ?? null;
+  }
+  /**
+   * Remove a game from the registry. Returns `true` if a game was actually
+   * removed; `false` if `gameId` was not registered.
+   */
+  unregister(gameId) {
+    const key = gameId;
+    return this.entries.delete(key);
+  }
+  /** Number of registered games. Mostly useful in tests. */
+  get size() {
+    return this.entries.size;
+  }
+  /** List of registered game IDs (snapshot copy). */
+  list() {
+    return Array.from(this.entries.keys());
+  }
+};
+
+// src/register-plugin.ts
+import { setupMatch } from "@table-games-engine/core";
+function registerPlugin(registry, plugin) {
+  return registry.register({
+    gameId: plugin.id,
+    manifest: plugin.manifest,
+    handlers: plugin.actionHandlers,
+    // Same seed shape the TCG glue used, so existing matches replay identically.
+    setup: (matchId, playerIds, config, ctx) => setupMatch(plugin, { playerIds, config, seed: `${String(matchId)}-${ctx.now}` }),
+    ...plugin.winConditionChecker ? { winChecker: plugin.winConditionChecker } : {},
+    ...plugin.stateBasedActions ? { stateBasedActions: plugin.stateBasedActions } : {},
+    ...plugin.legalMoves ? { legalMoves: plugin.legalMoves } : {}
+  });
+}
+
+// src/idempotency.ts
+var DEFAULT_TTL_MS = 5 * 60 * 1e3;
+var IdempotencyCache = class {
+  buckets;
+  ttlMs;
+  now;
+  constructor(options = {}) {
+    this.buckets = /* @__PURE__ */ new Map();
+    this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    this.now = options.now ?? (() => Date.now());
+  }
+  /**
+   * Look up a cached response. Prunes expired entries for the match as a
+   * side effect, so a stale entry is never returned.
+   */
+  get(matchId, clientId) {
+    const bucket = this.buckets.get(matchId);
+    if (!bucket) return null;
+    this.pruneBucket(bucket);
+    const entry = bucket.get(clientId);
+    return entry ? entry.response : null;
+  }
+  /**
+   * Cache `response` under `(matchId, clientId)` with TTL. Replaces any
+   * existing entry for the same key.
+   */
+  set(matchId, clientId, response) {
+    let bucket = this.buckets.get(matchId);
+    if (!bucket) {
+      bucket = /* @__PURE__ */ new Map();
+      this.buckets.set(matchId, bucket);
+    }
+    this.pruneBucket(bucket);
+    bucket.set(clientId, {
+      response,
+      expiresAt: this.now() + this.ttlMs
+    });
+  }
+  /**
+   * Drop the entire bucket for `matchId`. Use when a match terminates so
+   * we don't hold the response payloads in memory.
+   */
+  clear(matchId) {
+    this.buckets.delete(matchId);
+  }
+  /**
+   * Walk every bucket and drop expired entries. Empty buckets are removed.
+   */
+  prune() {
+    for (const [matchId, bucket] of this.buckets) {
+      this.pruneBucket(bucket);
+      if (bucket.size === 0) {
+        this.buckets.delete(matchId);
+      }
+    }
+  }
+  /** Total number of live entries across all buckets. Test-only helper. */
+  get size() {
+    let total = 0;
+    for (const bucket of this.buckets.values()) total += bucket.size;
+    return total;
+  }
+  pruneBucket(bucket) {
+    const cutoff = this.now();
+    for (const [clientId, entry] of bucket) {
+      if (entry.expiresAt <= cutoff) {
+        bucket.delete(clientId);
+      }
+    }
+  }
+};
+
+// src/match-handler.ts
+import { computePlayerView as computePlayerView2, createEngine, driveAction } from "@table-games-engine/core";
+
+// src/broadcast.ts
+import { computePlayerView } from "@table-games-engine/core";
+var OPCODES = {
+  STATE_UPDATE: 1,
+  ACK: 2,
+  BROADCAST: 3,
+  MATCH_ENDED: 4,
+  TRANSITION: 5
+};
+function broadcastViews(state, manifest, dispatcher, presences, legalMovesFor) {
+  for (const presence of presences) {
+    const viewerId = presence.userId;
+    if (!state.players[viewerId]) continue;
+    const view = computePlayerView(state, manifest, viewerId);
+    const envelope = {
+      kind: "state",
+      view,
+      version: view.version,
+      ...legalMovesFor ? { legalMoves: legalMovesFor(viewerId) } : {}
+    };
+    dispatcher.broadcastMessage(
+      OPCODES.STATE_UPDATE,
+      serializeOutbound(envelope),
+      [presence],
+      null,
+      true
+    );
+  }
+}
+
+// src/timeouts.ts
+function checkTimeouts(state, now, timeoutMs, priorityHeldSince) {
+  const holder = state.priority.holder;
+  if (!holder) return null;
+  if (priorityHeldSince === null) return null;
+  if (now - priorityHeldSince < timeoutMs) return null;
+  const stateVersion = state.version;
+  return {
+    playerId: holder,
+    type: "timeout",
+    data: { type: "timeout", reason: "action_timeout" },
+    clientId: `timeout-${stateVersion}`,
+    stateVersion
+  };
+}
+
+// src/persistence-bridge.ts
+import {
+  checksumState,
+  everyNTransitions
+} from "@table-games-engine/persistence";
+function createPersistenceBridge(args) {
+  const {
+    adapter,
+    matchId,
+    policy = everyNTransitions(50)
+  } = args;
+  let transitionsSince = 0;
+  let lastSnapshotTick = -Infinity;
+  let lastVersionPersisted = -Infinity;
+  let initialSnapshotted = false;
+  async function snapshotNow(state) {
+    await adapter.persistSnapshot(matchId, state, checksumState(state));
+    transitionsSince = 0;
+    lastSnapshotTick = state.tick;
+  }
+  return {
+    matchId,
+    adapter,
+    async persistInitialSnapshot(state) {
+      if (initialSnapshotted) return;
+      initialSnapshotted = true;
+      lastVersionPersisted = state.version;
+      await snapshotNow(state);
+    },
+    async persistTransition(transition, postState) {
+      const tv = transition.toVersion;
+      if (tv <= lastVersionPersisted) {
+        return;
+      }
+      lastVersionPersisted = tv;
+      const events = transition.events;
+      if (events.length > 0) {
+        await adapter.appendEvents(matchId, transition.toVersion, events);
+      }
+      transitionsSince += 1;
+      const ticksSince = postState.tick - lastSnapshotTick;
+      if (policy.shouldSnapshot(postState, { transitionsSince, ticksSince })) {
+        await snapshotNow(postState);
+      }
+    },
+    async forceSnapshot(state) {
+      await snapshotNow(state);
+    }
+  };
+}
+
+// src/plugins.ts
+function invokePluginHook(logger, pluginName, hookName, fn) {
+  let result;
+  try {
+    result = fn();
+  } catch (e) {
+    logger.error(
+      "plugin %s hook %s threw synchronously: %s",
+      pluginName,
+      hookName,
+      e instanceof Error ? e.message : String(e)
+    );
+    return;
+  }
+  if (result && typeof result.then === "function") {
+    result.catch((e) => {
+      logger.error(
+        "plugin %s hook %s rejected: %s",
+        pluginName,
+        hookName,
+        e instanceof Error ? e.message : String(e)
+      );
+    });
+  }
+}
+function dispatchPluginHook(plugins, logger, hookName, invoke) {
+  if (!plugins || plugins.length === 0) return;
+  for (let i = 0; i < plugins.length; i++) {
+    const plugin = plugins[i];
+    if (typeof plugin[hookName] !== "function") {
+      continue;
+    }
+    const name = plugin.name ?? `plugin#${i}`;
+    invokePluginHook(logger, name, hookName, () => invoke(plugin));
+  }
+}
+
+// src/match-handler.ts
+var DEFAULT_LEASE_SECONDS = 60;
+function buildLabel(gameId, status) {
+  return JSON.stringify({ gameId, status });
+}
+function bytesToString(bytes) {
+  if (typeof TextDecoder !== "undefined") {
+    try {
+      return new TextDecoder().decode(bytes);
+    } catch {
+    }
+  }
+  let out = "";
+  let i = 0;
+  const len = bytes.length;
+  while (i < len) {
+    const b1 = bytes[i++];
+    if (b1 < 128) {
+      out += String.fromCharCode(b1);
+    } else if (b1 < 192) {
+      out += String.fromCharCode(b1);
+    } else if (b1 < 224) {
+      const b2 = bytes[i++] & 63;
+      out += String.fromCharCode((b1 & 31) << 6 | b2);
+    } else if (b1 < 240) {
+      const b2 = bytes[i++] & 63;
+      const b3 = bytes[i++] & 63;
+      out += String.fromCharCode((b1 & 15) << 12 | b2 << 6 | b3);
+    } else {
+      const b2 = bytes[i++] & 63;
+      const b3 = bytes[i++] & 63;
+      const b4 = bytes[i++] & 63;
+      const cp = (b1 & 7) << 18 | b2 << 12 | b3 << 6 | b4;
+      const sub = cp - 65536;
+      out += String.fromCharCode(55296 + (sub >> 10), 56320 + (sub & 1023));
+    }
+  }
+  return out;
+}
+function decodeInbound(data) {
+  try {
+    if (typeof data === "string") return data;
+    if (data === null || data === void 0) return "";
+    const tag = Object.prototype.toString.call(data);
+    if (tag === "[object ArrayBuffer]") {
+      return bytesToString(new Uint8Array(data));
+    }
+    if (tag === "[object Uint8Array]" || tag === "[object Int8Array]" || tag === "[object Uint8ClampedArray]") {
+      return bytesToString(data);
+    }
+    const obj = data;
+    if (obj.buffer && Object.prototype.toString.call(obj.buffer) === "[object ArrayBuffer]") {
+      return bytesToString(new Uint8Array(obj.buffer));
+    }
+    const len = typeof obj.byteLength === "number" ? obj.byteLength : typeof obj.length === "number" ? obj.length : 0;
+    if (len > 0) {
+      const buf = new Uint8Array(len);
+      for (let i = 0; i < len; i++) buf[i] = obj[i] ?? 0;
+      return bytesToString(buf);
+    }
+  } catch {
+  }
+  return "";
+}
+function resolveOrThrow(registry, gameId) {
+  const entry = registry.resolve(gameId);
+  if (!entry) {
+    throw new Error(`createMatchHandler: unknown gameId '${gameId}'`);
+  }
+  return entry;
+}
+function ackOk(clientId) {
+  return { kind: "ack", clientId, ok: true };
+}
+function ackErr(clientId, code, message) {
+  return {
+    kind: "ack",
+    clientId,
+    ok: false,
+    error: { code, message }
+  };
+}
+function buildActionInput(env, sender) {
+  switch (env.kind) {
+    case "action":
+      return {
+        playerId: sender.userId,
+        type: "action",
+        data: env.action,
+        clientId: env.clientId,
+        stateVersion: env.stateVersion
+      };
+    case "pass":
+      return {
+        playerId: sender.userId,
+        type: "pass",
+        data: { type: "pass" },
+        clientId: env.clientId,
+        stateVersion: env.stateVersion
+      };
+    case "concede":
+      return {
+        playerId: sender.userId,
+        type: "concede",
+        data: { type: "concede" },
+        clientId: env.clientId,
+        stateVersion: env.stateVersion
+      };
+    case "choose-targets":
+      return {
+        playerId: sender.userId,
+        type: "choose_targets",
+        data: env.action,
+        clientId: env.clientId,
+        stateVersion: env.stateVersion
+      };
+    case "order-triggers":
+      return {
+        playerId: sender.userId,
+        type: "order_triggers",
+        data: env.action,
+        clientId: env.clientId,
+        stateVersion: env.stateVersion
+      };
+    case "admin-pause":
+    case "admin-resume":
+      return null;
+  }
+}
+function isMalformed(env) {
+  return env.kind === "malformed";
+}
+function sendAck(dispatcher, ack, presence) {
+  dispatcher.broadcastMessage(
+    OPCODES.ACK,
+    serializeOutbound(ack),
+    [presence],
+    null,
+    true
+  );
+}
+function movesFor(s) {
+  const legalMoves = s.legalMoves;
+  if (!legalMoves) return void 0;
+  return (p) => s.engineState.result || s.engineState.priority.holder !== p ? [] : legalMoves(s.engineState, p);
+}
+function sendViewToPresence(state, manifest, dispatcher, presence, legalMovesFor) {
+  const viewerId = presence.userId;
+  if (!state.players[viewerId]) return;
+  const view = computePlayerView2(state, manifest, viewerId);
+  const env = {
+    kind: "state",
+    view,
+    version: view.version,
+    ...legalMovesFor ? { legalMoves: legalMovesFor(viewerId) } : {}
+  };
+  dispatcher.broadcastMessage(
+    OPCODES.STATE_UPDATE,
+    serializeOutbound(env),
+    [presence],
+    null,
+    true
+  );
+}
+function createMatchHandler(options) {
+  const {
+    registry,
+    idempotencyCache,
+    matchIdFactory,
+    now = () => Date.now(),
+    timeout,
+    tickRate = 1,
+    adapter,
+    policy,
+    ownerNode,
+    leaseSeconds = DEFAULT_LEASE_SECONDS,
+    plugins
+  } = options;
+  const bridges = /* @__PURE__ */ new Map();
+  function bridgeFor(matchId) {
+    if (!adapter) return null;
+    const key = matchId;
+    let b = bridges.get(key);
+    if (!b) {
+      b = createPersistenceBridge({
+        adapter,
+        matchId,
+        ...policy ? { policy } : {}
+      });
+      bridges.set(key, b);
+    }
+    return b;
+  }
+  function pluginCtxFor(state) {
+    return {
+      matchId: state.matchId,
+      gameId: state.gameId,
+      state: state.engineState,
+      now: now()
+    };
+  }
+  async function persistTransitions(bridge, transitions, finalState) {
+    if (!bridge || transitions.length === 0) return;
+    for (const t of transitions) {
+      await bridge.persistTransition(t, finalState);
+    }
+  }
+  function matchInit(_ctx, logger, _nk, params) {
+    const gameIdParam = params["gameId"];
+    if (!gameIdParam) {
+      throw new Error('matchInit: missing required param "gameId"');
+    }
+    const gameId = gameIdParam;
+    const entry = resolveOrThrow(registry, gameId);
+    const matchIdRaw = params["matchId"] ?? (matchIdFactory ? matchIdFactory(now()) : `match-${now()}`);
+    const matchId = matchIdRaw;
+    const playerIdsParam = params["playerIds"];
+    const playerIds = playerIdsParam ? playerIdsParam.split(",") : [];
+    const config = params["config"] ? JSON.parse(params["config"]) : {};
+    const engineState = entry.setup(matchId, playerIds, config, { now: now() });
+    const state = {
+      matchId,
+      gameId,
+      engineState,
+      manifest: entry.manifest,
+      handlers: entry.handlers,
+      ...entry.stateBasedActions ? { stateBasedActions: entry.stateBasedActions } : {},
+      ...entry.winChecker ? { winChecker: entry.winChecker } : {},
+      ...entry.legalMoves ? { legalMoves: entry.legalMoves } : {},
+      presences: {},
+      status: "lobby",
+      priorityHeldSince: null,
+      lastPriorityHolder: null
+    };
+    if (adapter) {
+      const bridge = bridgeFor(matchId);
+      if (ownerNode !== void 0) {
+        adapter.acquireOwnership(matchId, ownerNode, leaseSeconds).then((acquired) => {
+          if (!acquired) {
+            logger.error(
+              "matchInit: ownership lease denied for match=%s owner=%s",
+              String(matchId),
+              ownerNode
+            );
+          }
+        }).catch((e) => {
+          logger.error(
+            "matchInit: acquireOwnership failed: %s",
+            e instanceof Error ? e.message : String(e)
+          );
+        });
+      }
+      bridge.persistInitialSnapshot(engineState).catch((e) => {
+        logger.error(
+          "matchInit: persistInitialSnapshot failed: %s",
+          e instanceof Error ? e.message : String(e)
+        );
+      });
+    }
+    dispatchPluginHook(
+      plugins,
+      logger,
+      "onMatchCreated",
+      (p) => p.onMatchCreated(pluginCtxFor(state))
+    );
+    logger.info(
+      "matchInit: matchId=%s gameId=%s seats=%d",
+      matchId,
+      gameId,
+      playerIds.length
+    );
+    return {
+      state,
+      tickRate,
+      label: buildLabel(gameId, state.status)
+    };
+  }
+  function matchJoinAttempt(_ctx, _logger, _nk, _dispatcher, _tick, state, presence, _metadata) {
+    if (state.status === "finished") {
+      return {
+        state,
+        accept: false,
+        rejectMessage: "match already finished"
+      };
+    }
+    if (state.presences[presence.userId]) {
+      return { state, accept: true };
+    }
+    const seatsTaken = Object.keys(state.presences).length;
+    const cap = state.manifest.maxPlayers ?? Number.POSITIVE_INFINITY;
+    if (seatsTaken >= cap) {
+      return { state, accept: false, rejectMessage: "match is full" };
+    }
+    return { state, accept: true };
+  }
+  function matchJoin(_ctx, logger, _nk, dispatcher, _tick, state, presences) {
+    const nextPresences = { ...state.presences };
+    const reconnecting = [];
+    const fresh = [];
+    for (const p of presences) {
+      const existed = state.presences[p.userId] !== void 0 || state.engineState.players[p.userId] !== void 0;
+      if (existed) reconnecting.push(p);
+      else fresh.push(p);
+      nextPresences[p.userId] = p;
+    }
+    const seatsFilled = Object.keys(nextPresences).length;
+    const wasLobby = state.status === "lobby";
+    let nextStatus = state.status;
+    if (state.status === "lobby" && seatsFilled >= (state.manifest.minPlayers ?? 1)) {
+      nextStatus = "active";
+    }
+    const next = {
+      ...state,
+      presences: nextPresences,
+      status: nextStatus
+    };
+    logger.info(
+      "matchJoin: matchId=%s newSeats=%d total=%d status=%s reconnects=%d",
+      next.matchId,
+      fresh.length,
+      seatsFilled,
+      next.status,
+      reconnecting.length
+    );
+    for (const p of reconnecting) {
+      sendViewToPresence(next.engineState, next.manifest, dispatcher, p, movesFor(next));
+    }
+    if (fresh.length > 0) {
+      broadcastViews(
+        next.engineState,
+        next.manifest,
+        dispatcher,
+        Object.values(next.presences),
+        movesFor(next)
+      );
+    }
+    const ctx = pluginCtxFor(next);
+    for (const p of presences) {
+      dispatchPluginHook(
+        plugins,
+        logger,
+        "onPlayerJoined",
+        (plugin) => plugin.onPlayerJoined(ctx, p)
+      );
+    }
+    if (wasLobby && next.status === "active") {
+      dispatchPluginHook(
+        plugins,
+        logger,
+        "onMatchStarted",
+        (plugin) => plugin.onMatchStarted(ctx)
+      );
+    }
+    return { state: next };
+  }
+  function matchLeave(_ctx, logger, _nk, dispatcher, _tick, state, presences) {
+    const nextPresences = { ...state.presences };
+    let priorityHolderLeft = false;
+    for (const p of presences) {
+      if (state.engineState.priority.holder === p.userId) {
+        priorityHolderLeft = true;
+      }
+      delete nextPresences[p.userId];
+    }
+    let next = { ...state, presences: nextPresences };
+    const transitions = [];
+    if (priorityHolderLeft && state.engineState.priority.holder) {
+      const holder = state.engineState.priority.holder;
+      const timeoutInput = {
+        playerId: holder,
+        type: "timeout",
+        data: { type: "timeout", reason: "leaver_timeout" },
+        clientId: `system-leave-${state.engineState.version}`,
+        stateVersion: state.engineState.version
+      };
+      try {
+        const r = driveAction(next, next.engineState, timeoutInput);
+        if (r.ok) {
+          transitions.push(...r.transitions);
+          next = { ...next, engineState: r.state };
+        } else {
+          logger.warn(
+            "matchLeave: synthetic timeout rejected: %s",
+            JSON.stringify(r.error)
+          );
+        }
+      } catch (e) {
+        logger.error("matchLeave: game logic threw: %s", e instanceof Error ? e.message : String(e));
+      }
+    }
+    const bridge = bridgeFor(next.matchId);
+    if (bridge && transitions.length > 0) {
+      persistTransitions(bridge, transitions, next.engineState).catch(
+        (e) => {
+          logger.error(
+            "matchLeave: persist failed: %s",
+            e instanceof Error ? e.message : String(e)
+          );
+        }
+      );
+    }
+    logger.info(
+      "matchLeave: matchId=%s left=%d remaining=%d",
+      next.matchId,
+      presences.length,
+      Object.keys(next.presences).length
+    );
+    broadcastViews(
+      next.engineState,
+      next.manifest,
+      dispatcher,
+      Object.values(next.presences),
+      movesFor(next)
+    );
+    const ctx = pluginCtxFor(next);
+    for (const p of presences) {
+      dispatchPluginHook(
+        plugins,
+        logger,
+        "onPlayerLeft",
+        (plugin) => plugin.onPlayerLeft(ctx, p)
+      );
+    }
+    for (const t of transitions) {
+      dispatchPluginHook(
+        plugins,
+        logger,
+        "onStateTransition",
+        (plugin) => plugin.onStateTransition(ctx, t)
+      );
+    }
+    return { state: next };
+  }
+  function matchLoop(_ctx, logger, _nk, dispatcher, _tick, state, messages) {
+    let working = state;
+    let stateChanged = false;
+    const transitions = [];
+    const playerActionTransitions = [];
+    for (const msg of messages) {
+      const sender = msg.sender;
+      const json = decodeInbound(msg.data);
+      const env = parseInbound(json);
+      if (isMalformed(env)) {
+        logger.warn(
+          "matchLoop: malformed envelope reason=%s detail=%s preview=%s",
+          env.reason,
+          String(env.detail ?? ""),
+          json.slice(0, 200)
+        );
+        const ack = ackErr(
+          "unknown",
+          "malformed",
+          env.detail ? `${env.reason}: ${env.detail}` : env.reason
+        );
+        sendAck(dispatcher, ack, sender);
+        continue;
+      }
+      if (env.kind === "admin-pause" || env.kind === "admin-resume") {
+        const ack = ackErr(
+          env.clientId,
+          "invalid-channel",
+          "admin envelopes must be sent via matchSignal"
+        );
+        sendAck(dispatcher, ack, sender);
+        continue;
+      }
+      const matchKey = working.matchId;
+      const cached = idempotencyCache.get(matchKey, env.clientId);
+      if (cached) {
+        dispatcher.broadcastMessage(
+          OPCODES.ACK,
+          serializeOutbound(cached),
+          [sender],
+          null,
+          true
+        );
+        continue;
+      }
+      const input = buildActionInput(env, sender);
+      if (!input) {
+        const ack = ackErr(env.clientId, "invalid", `unsupported envelope kind ${env.kind}`);
+        idempotencyCache.set(matchKey, env.clientId, ack);
+        sendAck(dispatcher, ack, sender);
+        continue;
+      }
+      let driven;
+      try {
+        driven = driveAction(working, working.engineState, input);
+      } catch (e) {
+        logger.error("matchLoop: game logic threw: %s", e instanceof Error ? e.message : String(e));
+        const ack = ackErr(env.clientId, "INTERNAL", "game logic error");
+        idempotencyCache.set(matchKey, env.clientId, ack);
+        sendAck(dispatcher, ack, sender);
+        continue;
+      }
+      let ackEnv;
+      if (driven.ok) {
+        ackEnv = ackOk(env.clientId);
+        transitions.push(...driven.transitions);
+        const first = driven.transitions[0];
+        if (first) playerActionTransitions.push({ input, transition: first });
+        working = { ...working, engineState: driven.state };
+        stateChanged = true;
+      } else {
+        const v = driven.error;
+        ackEnv = v.valid ? ackErr(env.clientId, "INTERNAL", "unknown error") : ackErr(env.clientId, v.error.code, v.error.message);
+      }
+      idempotencyCache.set(matchKey, env.clientId, ackEnv);
+      dispatcher.broadcastMessage(
+        OPCODES.ACK,
+        serializeOutbound(ackEnv),
+        [sender],
+        null,
+        true
+      );
+    }
+    if (timeout && working.status !== "finished" && !working.engineState.result) {
+      const currentHolder = working.engineState.priority.holder ?? null;
+      if (currentHolder !== working.lastPriorityHolder) {
+        working = {
+          ...working,
+          lastPriorityHolder: currentHolder ?? null,
+          priorityHeldSince: now()
+        };
+      }
+      const timeoutInput = checkTimeouts(
+        working.engineState,
+        now(),
+        timeout.timeoutMs,
+        working.priorityHeldSince
+      );
+      if (timeoutInput) {
+        try {
+          const r = driveAction(working, working.engineState, timeoutInput);
+          if (r.ok) {
+            transitions.push(...r.transitions);
+            working = {
+              ...working,
+              engineState: r.state,
+              priorityHeldSince: now()
+            };
+            stateChanged = true;
+          } else {
+            logger.warn(
+              "matchLoop: timeout injection rejected: %s",
+              JSON.stringify(r.error)
+            );
+          }
+        } catch (e) {
+          logger.error("matchLoop: game logic threw on timeout: %s", e instanceof Error ? e.message : String(e));
+        }
+      }
+    }
+    const bridge = bridgeFor(working.matchId);
+    if (bridge && transitions.length > 0) {
+      persistTransitions(bridge, transitions, working.engineState).catch(
+        (e) => {
+          logger.error(
+            "matchLoop: persist failed: %s",
+            e instanceof Error ? e.message : String(e)
+          );
+        }
+      );
+    }
+    if (stateChanged) {
+      broadcastViews(
+        working.engineState,
+        working.manifest,
+        dispatcher,
+        Object.values(working.presences),
+        movesFor(working)
+      );
+    }
+    if (transitions.length > 0) {
+      const ctx = pluginCtxFor(working);
+      for (const { input, transition } of playerActionTransitions) {
+        dispatchPluginHook(
+          plugins,
+          logger,
+          "onPlayerAction",
+          (plugin) => plugin.onPlayerAction(ctx, input, transition)
+        );
+      }
+      for (const t of transitions) {
+        dispatchPluginHook(
+          plugins,
+          logger,
+          "onStateTransition",
+          (plugin) => plugin.onStateTransition(ctx, t)
+        );
+      }
+    }
+    const endResult = working.status === "finished" ? null : working.engineState.result ?? (() => {
+      const c = createEngine(working.manifest, working.engineState, working.handlers).checkWinConditions();
+      return c.ended ? c.result : null;
+    })();
+    if (endResult) {
+      const ended = {
+        kind: "match-ended",
+        result: endResult
+      };
+      dispatcher.broadcastMessage(
+        OPCODES.MATCH_ENDED,
+        serializeOutbound(ended),
+        null,
+        null,
+        true
+      );
+      working = { ...working, status: "finished" };
+      const ctx = pluginCtxFor(working);
+      dispatchPluginHook(
+        plugins,
+        logger,
+        "onMatchEnded",
+        (plugin) => plugin.onMatchEnded(ctx, endResult)
+      );
+    }
+    return { state: working };
+  }
+  function matchSignal(_ctx, logger, _nk, _dispatcher, _tick, state, data) {
+    let parsed;
+    try {
+      const raw = JSON.parse(data);
+      if (typeof raw === "string") {
+        parsed = { type: raw };
+      } else if (raw && typeof raw === "object") {
+        parsed = raw;
+      } else {
+        return { state, data: JSON.stringify({ ok: false, error: "invalid" }) };
+      }
+    } catch {
+      parsed = { type: data };
+    }
+    let next = state;
+    switch (parsed.type) {
+      case "pause":
+        if (state.status === "active") {
+          next = { ...state, status: "paused" };
+          logger.info("matchSignal: paused matchId=%s", state.matchId);
+        }
+        return { state: next, data: JSON.stringify({ ok: true, status: next.status }) };
+      case "resume":
+        if (state.status === "paused") {
+          next = { ...state, status: "active" };
+          logger.info("matchSignal: resumed matchId=%s", state.matchId);
+        }
+        return { state: next, data: JSON.stringify({ ok: true, status: next.status }) };
+      case "force-end":
+        next = { ...state, status: "finished" };
+        logger.info("matchSignal: force-end matchId=%s", state.matchId);
+        return { state: next, data: JSON.stringify({ ok: true, status: next.status }) };
+      case "eject": {
+        const playerId = parsed.playerId;
+        if (!playerId) {
+          return {
+            state,
+            data: JSON.stringify({ ok: false, error: "eject: missing playerId" })
+          };
+        }
+        const ejectInput = {
+          playerId,
+          type: "concede",
+          data: { type: "concede" },
+          clientId: `system-eject-${state.engineState.version}`,
+          stateVersion: state.engineState.version
+        };
+        const stateForEject = {
+          ...state.engineState,
+          priority: {
+            ...state.engineState.priority,
+            holder: playerId
+          }
+        };
+        let r;
+        try {
+          r = driveAction(state, stateForEject, ejectInput);
+        } catch (e) {
+          logger.error("matchSignal: game logic threw on eject: %s", e instanceof Error ? e.message : String(e));
+          return { state, data: JSON.stringify({ ok: false, error: "eject failed" }) };
+        }
+        if (!r.ok) {
+          logger.warn("matchSignal: eject rejected: %s", JSON.stringify(r.error));
+          return {
+            state,
+            data: JSON.stringify({ ok: false, error: "eject failed" })
+          };
+        }
+        const ejectTransitions = [...r.transitions];
+        const prevHolder = state.engineState.priority.holder;
+        const keepHolder = prevHolder && prevHolder !== playerId && !r.state.result && r.state.players[prevHolder]?.status !== "eliminated" && r.state.turn.turnNumber === state.engineState.turn.turnNumber;
+        const drained = keepHolder ? { ...r.state, priority: { ...r.state.priority, holder: prevHolder } } : r.state;
+        const newPresences = { ...state.presences };
+        delete newPresences[playerId];
+        next = {
+          ...state,
+          engineState: drained,
+          presences: newPresences
+        };
+        const bridge = bridgeFor(next.matchId);
+        if (bridge) {
+          persistTransitions(bridge, ejectTransitions, next.engineState).catch(
+            (e) => {
+              logger.error(
+                "matchSignal:eject persist failed: %s",
+                e instanceof Error ? e.message : String(e)
+              );
+            }
+          );
+        }
+        return { state: next, data: JSON.stringify({ ok: true, ejected: playerId }) };
+      }
+      default:
+        return {
+          state,
+          data: JSON.stringify({ ok: false, error: `unknown signal: ${parsed.type}` })
+        };
+    }
+  }
+  function matchTerminate(_ctx, logger, _nk, _dispatcher, _tick, state, graceSeconds) {
+    logger.info(
+      "matchTerminate: matchId=%s grace=%ds",
+      state.matchId,
+      graceSeconds
+    );
+    idempotencyCache.clear(state.matchId);
+    if (adapter && ownerNode !== void 0) {
+      adapter.releaseOwnership(state.matchId, ownerNode).catch((e) => {
+        logger.error(
+          "matchTerminate: releaseOwnership failed: %s",
+          e instanceof Error ? e.message : String(e)
+        );
+      });
+    }
+    bridges.delete(state.matchId);
+    return { state: { ...state, status: "finished" } };
+  }
+  return {
+    matchInit,
+    matchJoinAttempt,
+    matchJoin,
+    matchLeave,
+    matchLoop,
+    matchTerminate,
+    matchSignal
+  };
+}
+export {
+  GameRegistry,
+  IdempotencyCache,
+  OPCODES,
+  RegistryError,
+  broadcastViews,
+  checkTimeouts,
+  createMatchHandler,
+  createPersistenceBridge,
+  dispatchPluginHook,
+  invokePluginHook,
+  parseInbound,
+  registerPlugin,
+  serializeOutbound
+};