@zhin.js/game-kit 2.0.1 → 2.0.2

package/lib/session-coordinator.js

@@ -0,0 +1,57 @@
+export class GameSessionConflictError extends Error {
+    requestedGameId;
+    activeGameId;
+    sessionId;
+    userId;
+    constructor(requestedGameId, activeGameId, sessionId, userId) {
+        super(`你在当前频道已有进行中的「${activeGameId}」对局，`
+            + `请先结束它，再开始「${requestedGameId}」。`);
+        this.requestedGameId = requestedGameId;
+        this.activeGameId = activeGameId;
+        this.sessionId = sessionId;
+        this.userId = userId;
+        this.name = 'GameSessionConflictError';
+    }
+}
+/**
+ * Cross-game active-session index. Registrations form per-game stacks so HMR
+ * can install a new generation before disposing the old one without a gap.
+ */
+export class GameSessionCoordinator {
+    #providers = new Map();
+    register(provider) {
+        const providers = this.#providers.get(provider.gameId) ?? [];
+        providers.push(provider);
+        this.#providers.set(provider.gameId, providers);
+        return () => {
+            const current = this.#providers.get(provider.gameId);
+            if (!current)
+                return;
+            const index = current.lastIndexOf(provider);
+            if (index >= 0)
+                current.splice(index, 1);
+            if (current.length === 0)
+                this.#providers.delete(provider.gameId);
+        };
+    }
+    async assertAvailable(requestedGameId, channelKey, userIds) {
+        for (const [gameId, registrations] of this.#providers) {
+            if (gameId === requestedGameId)
+                continue;
+            const provider = registrations[registrations.length - 1];
+            if (!provider)
+                continue;
+            for (const userId of new Set(userIds.filter(Boolean))) {
+                const active = await provider.getActiveForUser(channelKey, userId);
+                if (active) {
+                    throw new GameSessionConflictError(requestedGameId, gameId, active.id, userId);
+                }
+            }
+        }
+    }
+    clear() {
+        this.#providers.clear();
+    }
+}
+export const gameSessionCoordinator = new GameSessionCoordinator();
+//# sourceMappingURL=session-coordinator.js.map

package/lib/session-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-coordinator.js","sourceRoot":"","sources":["../src/session-coordinator.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAEtC;IACA;IACA;IACA;IAJX,YACW,eAAuB,EACvB,YAAoB,EACpB,SAAiB,EACjB,MAAc;QAEvB,KAAK,CACH,gBAAgB,YAAY,MAAM;cAChC,aAAa,eAAe,IAAI,CACnC,CAAC;QARO,oBAAe,GAAf,eAAe,CAAQ;QACvB,iBAAY,GAAZ,YAAY,CAAQ;QACpB,cAAS,GAAT,SAAS,CAAQ;QACjB,WAAM,GAAN,MAAM,CAAQ;QAMvB,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,sBAAsB;IACxB,UAAU,GAAG,IAAI,GAAG,EAAiC,CAAC;IAE/D,QAAQ,CAAC,QAA6B;QACpC,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC7D,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAChD,OAAO,GAAG,EAAE;YACV,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACrD,IAAI,CAAC,OAAO;gBAAE,OAAO;YACrB,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,KAAK,IAAI,CAAC;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACzC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACpE,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,eAAe,CACnB,eAAuB,EACvB,UAAkB,EAClB,OAA0B;QAE1B,KAAK,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACtD,IAAI,MAAM,KAAK,eAAe;gBAAE,SAAS;YACzC,MAAM,QAAQ,GAAG,aAAa,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACzD,IAAI,CAAC,QAAQ;gBAAE,SAAS;YACxB,KAAK,MAAM,MAAM,IAAI,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;gBACtD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,gBAAgB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;gBACnE,IAAI,MAAM,EAAE,CAAC;oBACX,MAAM,IAAI,wBAAwB,CAChC,eAAe,EACf,MAAM,EACN,MAAM,CAAC,EAAE,EACT,MAAM,CACP,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,sBAAsB,EAAE,CAAC"}

package/lib/versioned-session-service.d.ts

@@ -0,0 +1,48 @@
+import { BaseSessionService, type BaseGameSessionRow, type BaseSessionServiceOptions, type GameSessionDatabase } from './base-session-service.js';
+export interface VersionedGameSessionRow extends BaseGameSessionRow {
+    revision: number;
+    /** JSON string containing the bounded action-id history. */
+    processed_actions: string;
+}
+export interface SessionMutationOptions<TRow extends VersionedGameSessionRow> {
+    readonly actionId: string;
+    readonly expectedRevision?: number;
+    readonly apply: Partial<TRow> | ((session: Readonly<TRow>) => Partial<TRow> | Promise<Partial<TRow>>);
+}
+export type SessionMutationResult<TRow extends VersionedGameSessionRow> = {
+    readonly kind: 'applied';
+    readonly session: TRow;
+} | {
+    readonly kind: 'duplicate';
+    readonly session: TRow;
+};
+export declare class SessionNotFoundError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+export declare class SessionRevisionConflictError extends Error {
+    readonly sessionId: string;
+    readonly expectedRevision: number;
+    readonly actualRevision: number;
+    constructor(sessionId: string, expectedRevision: number, actualRevision: number);
+}
+/**
+ * A keyed promise queue. It prevents lost updates inside one runtime while the
+ * persisted revision check protects deployments that share a database.
+ */
+export declare class SessionActionGate {
+    #private;
+    run<TResult>(sessionId: string, action: () => TResult | Promise<TResult>): Promise<TResult>;
+    get pendingSessions(): number;
+}
+/**
+ * Adds serialized, optimistic and idempotent mutations to BaseSessionService.
+ * Action ids are intentionally persisted so adapter retries remain harmless
+ * after a process restart.
+ */
+export declare abstract class VersionedSessionService<TRow extends VersionedGameSessionRow> extends BaseSessionService<TRow> {
+    #private;
+    protected constructor(database: GameSessionDatabase<TRow>, options: BaseSessionServiceOptions<TRow>);
+    mutateSession(id: string, options: SessionMutationOptions<TRow>): Promise<SessionMutationResult<TRow>>;
+}
+//# sourceMappingURL=versioned-session-service.d.ts.map

package/lib/versioned-session-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-session-service.d.ts","sourceRoot":"","sources":["../src/versioned-session-service.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AAInC,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB,CAAC,IAAI,SAAS,uBAAuB;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EACV,OAAO,CAAC,IAAI,CAAC,GACb,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,KACzB,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;CAC7C;AAED,MAAM,MAAM,qBAAqB,CAAC,IAAI,SAAS,uBAAuB,IAClE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC;AAE3D,qBAAa,oBAAqB,SAAQ,KAAK;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAIvC;AAED,qBAAa,4BAA6B,SAAQ,KAAK;IAEnD,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM;gBAFtB,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,MAAM;CAQlC;AAED;;;GAGG;AACH,qBAAa,iBAAiB;;IAGtB,GAAG,CAAC,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GACvC,OAAO,CAAC,OAAO,CAAC;IAiBnB,IAAI,eAAe,IAAI,MAAM,CAE5B;CACF;AAED;;;;GAIG;AACH,8BAAsB,uBAAuB,CAC3C,IAAI,SAAS,uBAAuB,CACpC,SAAQ,kBAAkB,CAAC,IAAI,CAAC;;IAIhC,SAAS,aACP,QAAQ,EAAE,mBAAmB,CAAC,IAAI,CAAC,EACnC,OAAO,EAAE,yBAAyB,CAAC,IAAI,CAAC;IAM1C,aAAa,CACX,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,sBAAsB,CAAC,IAAI,CAAC,GACpC,OAAO,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC;CAgDxC"}

package/lib/versioned-session-service.js

@@ -0,0 +1,116 @@
+import { BaseSessionService, } from './base-session-service.js';
+const DEFAULT_ACTION_HISTORY_LIMIT = 128;
+export class SessionNotFoundError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`Game session "${sessionId}" does not exist.`);
+        this.sessionId = sessionId;
+        this.name = 'SessionNotFoundError';
+    }
+}
+export class SessionRevisionConflictError extends Error {
+    sessionId;
+    expectedRevision;
+    actualRevision;
+    constructor(sessionId, expectedRevision, actualRevision) {
+        super(`Game session "${sessionId}" changed: expected revision `
+            + `${expectedRevision}, received ${actualRevision}.`);
+        this.sessionId = sessionId;
+        this.expectedRevision = expectedRevision;
+        this.actualRevision = actualRevision;
+        this.name = 'SessionRevisionConflictError';
+    }
+}
+/**
+ * A keyed promise queue. It prevents lost updates inside one runtime while the
+ * persisted revision check protects deployments that share a database.
+ */
+export class SessionActionGate {
+    #tails = new Map();
+    async run(sessionId, action) {
+        const previous = this.#tails.get(sessionId) ?? Promise.resolve();
+        let release = () => undefined;
+        const pending = new Promise((resolve) => {
+            release = resolve;
+        });
+        const tail = previous.catch(() => undefined).then(() => pending);
+        this.#tails.set(sessionId, tail);
+        await previous.catch(() => undefined);
+        try {
+            return await action();
+        }
+        finally {
+            release();
+            if (this.#tails.get(sessionId) === tail)
+                this.#tails.delete(sessionId);
+        }
+    }
+    get pendingSessions() {
+        return this.#tails.size;
+    }
+}
+/**
+ * Adds serialized, optimistic and idempotent mutations to BaseSessionService.
+ * Action ids are intentionally persisted so adapter retries remain harmless
+ * after a process restart.
+ */
+export class VersionedSessionService extends BaseSessionService {
+    #gate = new SessionActionGate();
+    #actionHistoryLimit;
+    constructor(database, options) {
+        super(database, options);
+        this.#actionHistoryLimit = DEFAULT_ACTION_HISTORY_LIMIT;
+    }
+    mutateSession(id, options) {
+        if (!options.actionId.trim()) {
+            return Promise.reject(new TypeError('actionId must not be empty'));
+        }
+        return this.#gate.run(id, async () => {
+            const previous = await this.getById(id);
+            if (!previous)
+                throw new SessionNotFoundError(id);
+            const processedActions = parseActionHistory(previous.processed_actions);
+            if (processedActions.includes(options.actionId)) {
+                return { kind: 'duplicate', session: previous };
+            }
+            if (options.expectedRevision !== undefined
+                && options.expectedRevision !== previous.revision) {
+                throw new SessionRevisionConflictError(id, options.expectedRevision, previous.revision);
+            }
+            const patch = typeof options.apply === 'function'
+                ? await options.apply(previous)
+                : options.apply;
+            const revision = previous.revision + 1;
+            const nextActions = [
+                ...processedActions,
+                options.actionId,
+            ].slice(-this.#actionHistoryLimit);
+            const session = await this.commitSession(previous, {
+                ...patch,
+                revision,
+                processed_actions: JSON.stringify(nextActions),
+            }, { id, revision: previous.revision });
+            if (!session
+                || session.revision !== revision
+                || !parseActionHistory(session.processed_actions).includes(options.actionId)) {
+                const actual = session?.revision
+                    ?? (await this.getById(id))?.revision
+                    ?? previous.revision;
+                throw new SessionRevisionConflictError(id, previous.revision, actual);
+            }
+            return { kind: 'applied', session };
+        });
+    }
+}
+function parseActionHistory(value) {
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((item) => typeof item === 'string');
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=versioned-session-service.js.map

package/lib/versioned-session-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-session-service.js","sourceRoot":"","sources":["../src/versioned-session-service.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/game-kit",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Zhin.js 游戏插件通用工具包",
   "type": "module",
   "main": "./lib/index.js",
@@ -13,8 +13,8 @@
     }
   },
   "peerDependencies": {
-    "zhin.js": "^5.0.1",
-    "@zhin.js/html-renderer": "2.0.1"
+    "zhin.js": "^5.0.2",
+    "@zhin.js/html-renderer": "2.0.2"
   },
   "peerDependenciesMeta": {
     "@zhin.js/html-renderer": {
@@ -22,13 +22,14 @@
     }
   },
   "dependencies": {
-    "@zhin.js/core": "1.4.1",
-    "@zhin.js/middleware": "1.0.3",
+    "@zhin.js/core": "1.4.2",
+    "@zhin.js/middleware": "1.0.4",
+    "@zhin.js/plugin-runtime": "1.1.1",
     "@zhin.js/satori": "1.0.17"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
-    "zhin.js": "5.0.1"
+    "zhin.js": "5.0.2"
   },
   "files": [
     "lib",

package/src/base-session-service.ts

@@ -0,0 +1,210 @@
+import {
+  gameEvents,
+  type GameEventSession,
+  type GameOutcome,
+} from './game-events.js';
+import { gameSessionCoordinator, type GameSessionProvider } from './session-coordinator.js';
+
+export interface BaseGameSessionRow extends GameEventSession {
+  id: string;
+  channel_key: string;
+  status: string;
+  updated_at: number;
+  created_at: number;
+  turn?: unknown;
+}
+
+export interface GameSessionModel<TRow extends BaseGameSessionRow> {
+  findAll(query?: Record<string, unknown>): Promise<TRow[]>;
+  findOne(query?: Record<string, unknown>): Promise<TRow | null>;
+  create(row: TRow): Promise<unknown>;
+  updateWhere(
+    where: Record<string, unknown>,
+    patch: Record<string, unknown>,
+  ): Promise<unknown>;
+}
+
+export interface GameSessionDatabase<TRow extends BaseGameSessionRow> {
+  readonly models: {
+    get(name: string): GameSessionModel<TRow> | undefined;
+  };
+}
+
+export interface BaseSessionServiceOptions<TRow extends BaseGameSessionRow> {
+  readonly gameId: string;
+  readonly table: string;
+  readonly userFields: readonly (keyof TRow & string)[];
+  readonly activeStatus?: string;
+  readonly abortedStatus?: string;
+  readonly projectOutcomes?: (
+    session: Readonly<TRow>,
+    previous: Readonly<TRow>,
+  ) => readonly GameOutcome[];
+}
+
+export type SessionTimeoutListener<TRow extends BaseGameSessionRow> = (
+  session: TRow,
+) => void | Promise<void>;
+
+/**
+ * Shared session lifecycle for every game. Subclasses own row construction and
+ * game-specific tables; this module owns persistence invariants and events.
+ */
+export abstract class BaseSessionService<TRow extends BaseGameSessionRow>
+implements GameSessionProvider {
+  readonly gameId: string;
+  readonly #activeStatus: string;
+  readonly #abortedStatus: string;
+  readonly #userFields: readonly (keyof TRow & string)[];
+  readonly #projectOutcomes?: BaseSessionServiceOptions<TRow>['projectOutcomes'];
+  readonly #model: GameSessionModel<TRow>;
+
+  protected constructor(
+    database: GameSessionDatabase<TRow>,
+    options: BaseSessionServiceOptions<TRow>,
+  ) {
+    const model = database.models.get(options.table);
+    if (!model) throw new Error(`${options.table} not registered`);
+    this.#model = model;
+    this.gameId = options.gameId;
+    this.#userFields = options.userFields;
+    this.#projectOutcomes = options.projectOutcomes;
+    this.#activeStatus = options.activeStatus ?? 'active';
+    this.#abortedStatus = options.abortedStatus ?? 'aborted';
+  }
+
+  async getById(id: string): Promise<TRow | null> {
+    return this.#model.findOne({ id });
+  }
+
+  async getActiveByChannel(channelKey: string): Promise<TRow | null> {
+    const rows = await this.#model.findAll({
+      channel_key: channelKey,
+      status: this.#activeStatus,
+    });
+    return rows[0] ?? null;
+  }
+
+  async getActiveForUser(channelKey: string, userId: string): Promise<TRow | null> {
+    const rows = await this.#model.findAll({
+      channel_key: channelKey,
+      status: this.#activeStatus,
+    });
+    return rows.find((row) =>
+      this.#userFields.some((field) => row[field] === userId)) ?? null;
+  }
+
+  async getLatestForUser(channelKey: string, userId: string): Promise<TRow | null> {
+    const rows = await this.#model.findAll({ channel_key: channelKey });
+    const matches = rows.filter((row) =>
+      this.#userFields.some((field) => row[field] === userId));
+    return matches.reduce<TRow | null>(
+      (latest, row) => !latest || row.updated_at >= latest.updated_at ? row : latest,
+      null,
+    );
+  }
+
+  async updateSession(id: string, patch: Partial<TRow>): Promise<void> {
+    const previous = await this.getById(id);
+    if (!previous) return;
+    await this.commitSession(previous, patch, { id });
+  }
+
+  /**
+   * Persist one transition and emit lifecycle events from the row that was
+   * actually stored. Versioned services use `where` for optimistic locking.
+   */
+  protected async commitSession(
+    previous: TRow,
+    patch: Partial<TRow>,
+    where: Record<string, unknown>,
+  ): Promise<TRow | null> {
+    const updatedAt = Date.now();
+    const changed = await this.#model.updateWhere(
+      where,
+      { ...patch, updated_at: updatedAt },
+    );
+    if (typeof changed === 'number' && changed === 0) return null;
+    const session = await this.getById(previous.id);
+    if (!session) return null;
+    if (patch.turn !== undefined && patch.turn !== previous.turn) {
+      await gameEvents.emit('turn:change', {
+        gameId: this.gameId,
+        session,
+        previousTurn: previous.turn,
+        turn: patch.turn,
+      });
+    }
+    if (patch.status !== undefined
+      && previous.status === this.#activeStatus
+      && patch.status !== this.#activeStatus) {
+      await gameEvents.emit('game:end', {
+        gameId: this.gameId,
+        session,
+        previousStatus: previous.status,
+        outcomes: this.#projectOutcomes?.(session, previous) ?? [],
+      });
+    }
+    return session;
+  }
+
+  async abortStale(
+    idleMs: number,
+    onTimeout?: SessionTimeoutListener<TRow>,
+  ): Promise<number> {
+    const cutoff = Date.now() - idleMs;
+    const rows = await this.#model.findAll({ status: this.#activeStatus });
+    let count = 0;
+    for (const row of rows) {
+      if (row.updated_at >= cutoff) continue;
+      // The timestamp condition prevents a cleanup scan from aborting a
+      // session that received a player action after this row was selected.
+      const session = await this.commitSession(
+        row,
+        { status: this.#abortedStatus } as Partial<TRow>,
+        {
+          id: row.id,
+          status: this.#activeStatus,
+          updated_at: row.updated_at,
+        },
+      );
+      if (!session) continue;
+      await gameEvents.emit('session:timeout', {
+        gameId: this.gameId,
+        session,
+        idleMs,
+      });
+      // A broken outbound adapter must not prevent later stale sessions from
+      // being finalized. Persistence and lifecycle events already succeeded.
+      if (onTimeout) {
+        try {
+          await onTimeout(session);
+        } catch {
+          // Notification is best-effort; the next cleanup pass stays healthy.
+        }
+      }
+      count += 1;
+    }
+    return count;
+  }
+
+  registerCoordinator(): () => void {
+    return gameSessionCoordinator.register(this);
+  }
+
+  protected async createRow(row: TRow): Promise<TRow> {
+    const userIds: string[] = [];
+    for (const field of this.#userFields) {
+      const value: unknown = row[field];
+      if (typeof value === 'string') userIds.push(value);
+    }
+    await gameSessionCoordinator.assertAvailable(this.gameId, row.channel_key, userIds);
+    await this.#model.create(row);
+    await gameEvents.emit('game:start', { gameId: this.gameId, session: row });
+    return row;
+  }
+
+  protected get model(): GameSessionModel<TRow> {
+    return this.#model;
+  }
+}

package/src/command-alias.ts

@@ -1,6 +1,8 @@
 import { defineMiddleware, type MiddlewareContext } from '@zhin.js/middleware';
 import type { Message } from '@zhin.js/core/runtime';
 
+type AliasReply = Parameters<Message['$reply']>[0];
+
 /**
  * 游戏 legacy 命令别名路由。
  *
@@ -20,7 +22,7 @@ export interface GameCommandAliasRoute {
     action: string,
     input: unknown,
     context: MiddlewareContext<Message>,
-  ): Promise<string | null | undefined>;
+  ): Promise<AliasReply | null | undefined>;
 }
 
 export function defineGameCommandAliasMiddleware(route: GameCommandAliasRoute) {

package/src/command-message.ts

@@ -4,6 +4,10 @@
  * Runtime Message: { adapter, target, sender?, metadata? }
  * Classic Message: { $adapter, $endpoint, $channel, $sender }
  */
+import type { SendContent } from '@zhin.js/core';
+
+/** A game returns semantic content; Runtime owns native rendering and text fallback. */
+export type GameReply = SendContent;
 
 export interface GameMessageLike {
   $adapter: string;

package/src/define-game-plugin.ts

@@ -0,0 +1,162 @@
+import {
+  databaseHostToken,
+  definePlugin,
+  outboundHostToken,
+  scheduleHostToken,
+  type DatabaseHost,
+  type PluginMetadata,
+  type PluginSetupContext,
+  type Token,
+} from '@zhin.js/plugin-runtime';
+import {
+  createHostGameDb,
+  createInMemoryGameDb,
+  type InMemoryGameDb,
+} from './memory-db.js';
+import {
+  initGameRecordHost,
+  recordGameOutcome,
+  type GameRecordDatabaseHost,
+} from './game-records.js';
+import { gameEvents } from './game-events.js';
+import {
+  DEFAULT_GAME_STALE_CRON,
+  DEFAULT_GAME_STALE_IDLE_MS,
+  registerRuntimeGame,
+  type RuntimeRegisteredGame,
+} from './runtime-hub.js';
+import type {
+  BaseGameSessionRow,
+  BaseSessionService,
+} from './base-session-service.js';
+
+export interface GamePluginSession<
+  TRow extends BaseGameSessionRow = BaseGameSessionRow,
+> {
+  abortStale(
+    idleMs: number,
+    onTimeout?: (session: TRow) => void | Promise<void>,
+  ): Promise<number>;
+  registerCoordinator?(): () => void;
+}
+
+export interface DefineGamePluginOptions<
+  TServices,
+  TRow extends BaseGameSessionRow = BaseGameSessionRow,
+  TConfig = unknown,
+> {
+  readonly name: string;
+  readonly metadata?: PluginMetadata;
+  readonly game: RuntimeRegisteredGame;
+  readonly tables: readonly string[];
+  readonly servicesToken: Token<TServices>;
+  readonly defineHostTables: (host: DatabaseHost) => void;
+  readonly createServices: (database: InMemoryGameDb) => TServices;
+  readonly session: (
+    services: TServices,
+  ) => GamePluginSession<TRow> | BaseSessionService<TRow>;
+  readonly stale?: {
+    readonly cron?: string;
+    readonly idleMs?: number;
+    readonly description?: string;
+    readonly message?: string | ((session: TRow) => string);
+    readonly onTimeout?: (
+      session: TRow,
+      context: PluginSetupContext<TConfig>,
+    ) => void | Promise<void>;
+  } | false;
+  readonly setup?: (
+    context: PluginSetupContext<TConfig>,
+    services: TServices,
+  ) => void | (() => void) | Promise<void | (() => void)>;
+}
+
+/**
+ * Declarative Plugin Runtime assembly for games. Database selection, service
+ * publication, Hub registration, stale cleanup and HMR disposal live here.
+ */
+export function defineGamePlugin<
+  TServices,
+  TRow extends BaseGameSessionRow = BaseGameSessionRow,
+  TConfig = unknown,
+>(
+  options: DefineGamePluginOptions<TServices, TRow, TConfig>,
+) {
+  return definePlugin<TConfig>({
+    name: options.name,
+    metadata: options.metadata,
+    async setup(context) {
+      let database: InMemoryGameDb;
+      if (context.resources.has(databaseHostToken)) {
+        const host = context.resources.use(databaseHostToken);
+        options.defineHostTables(host);
+        database = createHostGameDb(host, options.tables);
+        context.lifecycle.add(
+          initGameRecordHost(host as unknown as GameRecordDatabaseHost),
+        );
+      } else {
+        database = createInMemoryGameDb(options.tables);
+      }
+
+      const services = options.createServices(database);
+      context.resources.provide(options.servicesToken, services);
+
+      const session = options.session(services);
+      const disposeCoordinator = session.registerCoordinator?.();
+      if (disposeCoordinator) context.lifecycle.add(disposeCoordinator);
+      context.lifecycle.add(registerRuntimeGame(options.game));
+      context.lifecycle.add(gameEvents.on('game:end', async (event) => {
+        if (event.gameId !== options.game.id || event.outcomes.length === 0) return;
+        const row = event.session;
+        if (!row.adapter || !row.endpoint || !row.channel_type || !row.channel_id) return;
+        for (const outcome of event.outcomes) {
+          await recordGameOutcome({
+            $adapter: row.adapter,
+            $endpoint: row.endpoint,
+            $channel: { type: row.channel_type, id: row.channel_id },
+            $sender: {
+              id: outcome.userId,
+              name: outcome.userName ?? outcome.userId,
+            },
+          }, event.gameId, outcome.result, outcome.score);
+        }
+      }));
+
+      if (options.stale !== false && context.resources.has(scheduleHostToken)) {
+        const stale = options.stale ?? {};
+        const schedule = context.resources.use(scheduleHostToken);
+        context.lifecycle.add(schedule.register({
+          id: `${options.game.id}/abort-stale`,
+          cron: stale.cron ?? DEFAULT_GAME_STALE_CRON,
+          description: stale.description
+            ?? `Abort stale ${options.name} sessions`,
+          async execute() {
+            await session.abortStale(
+              stale.idleMs ?? DEFAULT_GAME_STALE_IDLE_MS,
+              async (row) => {
+                await stale.onTimeout?.(row, context);
+                if (!context.resources.has(outboundHostToken)) return;
+                if (!row.adapter || !row.endpoint
+                  || !row.channel_type || !row.channel_id) return;
+                const outbound = context.resources.use(outboundHostToken);
+                await outbound.send({
+                  adapter: row.adapter,
+                  endpointId: row.endpoint,
+                  channelType: row.channel_type,
+                  channelId: row.channel_id,
+                  content: typeof stale.message === 'function'
+                    ? stale.message(row)
+                    : stale.message
+                      ?? `${options.game.icon} ${options.game.title}对局因长时间无操作已结束。`,
+                });
+              },
+            );
+          },
+        }));
+      }
+
+      const dispose = await options.setup?.(context, services);
+      if (dispose) context.lifecycle.add(dispose);
+    },
+  });
+}