texas-poker-core 1.4.29 → 1.4.31

package/README.md

@@ -1,11 +1,14 @@
 # Texas-Poker-Core
 
 无服务、无持久化的 **德州扑克（Texas Hold’em）对局引擎**：房间与座位、盲注与角色、发牌、行动轮次、阶段推进、摊牌比牌、奖池与边池分配等规则均在库内完成。  
-**不包含**：账号系统、WebSocket/HTTP、数据库、匹配、UI；这些由业务层接入 `Texas` / `Room` / `Player` 的 API 与回调实现。
+**不包含**：账号系统、WebSocket/HTTP、数据库、匹配、UI、节拍与 `sleep`；这些由业务层解释 **领域事件** 并驱动 **`pendingFlowOps`** 队列实现。
 
-- **入口类**：`Texas` — 组装 `Pool`、`Dealer`、`Controller`、`Room`，并提供会话级方法。
-- **错误模型**：规则或状态不满足时通过 `TexasError`（`TexasCoreErrorCode`）**fail-fast**；可用 `onError` 先记录再抛出。
-- **可选节奏钩子**：构造 `Texas` 时传入 `beforeStageAdvance` / `beforeNextPlayerTurn`，在阶段切换、轮到下家前 `await`（例如发 WS、动画、`sleep`）。
+- **入口类**：`Texas` — 组装 `Pool`、`Dealer`、`Controller`、`Room`；状态变更写入事件缓冲，由业务 **`drainDomainEvents()`** 取出后落库 / 推送。
+- **指令入口**：玩家行动统一走 **`dispatchCommand(TableCommand)`**（自愿下注、超时、离场弃牌、入座大盲等）。
+- **节奏解耦**：进街与交权进入 **`pendingFlowOps`**（`stage_advance` | `turn_handoff`），业务按产品节拍调用 **`applyPendingStageAdvance`** / **`flushPendingTurnHandoff`**（单测可 **`flushAllPendingFlowOps`** 一次排空）。
+- **错误模型**：规则或状态不满足时 **`TexasError`（`TexasCoreErrorCode`）** fail-fast；`message` 为默认中文，业务可用 `code` + `payload` 做 i18n。
+
+**详细 API 清单**：[CORE_API.md](./CORE_API.md)。**与参考服务端的一整局事件流**：[docs/integration-core-wish-event-flow.md](./docs/integration-core-wish-event-flow.md)。
 
 ---
 
@@ -24,12 +27,12 @@ npm install texas-poker-core
 
 | 对象         | 职责                                                                                                                              |
 | ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| `Texas`      | 创建一桌、注册监听、`setPlayerRoles` / `dealCards` / `start` / `settle` / `reset` 等会话流程                                      |
+| `Texas`      | 会话门面：`setPlayerRoles` / `dealCards` / `start` / `dispatchCommand` / `drainDomainEvents` / 消费 `pendingFlowOps` / `reset` 等 |
 | `Room`       | 成员加入/观战/入座/离座、`initialRoles`（末 `lockSeats`）/ `rotateRoles`（不锁座）、`RoomStatus`（`seats_open` / `seats_locked`） |
-| `Dealer`     | 盲注、庄家、角色顺序、发牌、行动历史（通常不直接给业务大量调用，多经 `Texas` / `Room`）                                           |
-| `Controller` | 一手牌生命周期 `HandLifecycle`、当前街 `stage`、活跃玩家 `activePlayer`、阶段推进与终局                                           |
-| `Pool`       | 奖池与支付（`texas.settle()` 时 `pool.pay()`）                                                                                    |
-| `Player`     | 单个座位的筹码、手牌、行动 `check` / `bet` / `call` / `raise` / `fold` / `allIn` 与 `getControl`                                  |
+| `Dealer`     | 盲注、庄家、角色顺序、发牌（通常经 `Texas` / `Room` 访问）                                                                        |
+| `Controller` | 一手牌 `HandLifecycle`、当前街 `stage`、`activePlayer`、事件缓冲与 `pendingFlowOps` 队列                                          |
+| `Pool`       | 奖池与支付（`texas.settle()` 时 `pool.pay()`，并缓冲 `PotAwarded`）                                                               |
+| `Player`     | 单座筹码、手牌、允许行动集合；**勿**直接调 `check`/`bet`/…，统一经 `Texas#dispatchCommand`                                        |
 
 ---
 
@@ -52,30 +55,22 @@ npm install texas-poker-core
 
 ## 典型对局流程（使用手册）
 
-以下为常见顺序；具体校验与错误码以运行时 `TexasError` 为准。
+以下为常见顺序；具体校验与错误码以运行时 `TexasError` 为准。  
+**约定**：下列 `setPlayerRoles` / `dealCards` / `start` / `dispatchCommand` 等会 **同步返回** 本步 `TexasDomainEvent[]`（等价于随即 `drainDomainEvents()`）；若你自行多次调用 Core 再统一 drain，也可用 `texas.drainDomainEvents()` 取出缓冲。
 
 ### 1. 创建牌桌
 
 ```ts
-import { Texas } from 'texas-poker-core'
+import { Texas, type TableCommand } from 'texas-poker-core'
 
 const texas = new Texas({
   user: { id: 1, name: '房主' },
   lowestBetAmount: 20,
   maximumCountOfPlayers: 9,
-  initialChips: 2000,
-  // 可选：与 WS/动画对齐
-  beforeNextPlayerTurn: async () => {
-    /* await sleep(...) */
-  },
-  beforeStageAdvance: async () => {
-    /* ... */
-  }
+  initialChips: 2000
 })
 
-texas.onError((err) => {
-  // 日志、监控；随后仍会 throw
-})
+// 业务侧：try/catch TexasError，写日志 / 监控 / 映射 HTTP 状态码
 ```
 
 ### 2. 注册用户与入座
@@ -84,62 +79,155 @@ texas.onError((err) => {
 const p2 = texas.createPlayer({ id: 2, name: '玩家2' })
 texas.room.join(p2)
 texas.room.seat(p2)
-// join = 进房（默认观战席）；seat = 上桌，且要求房间 seats_open（一手收尾 reset 后）
+// join = 进房（默认观战）；seat = 上桌，须 seats_open（一手收尾 reset 后）
 ```
 
 ### 3. 锁座、分配角色、发牌
 
 ```ts
-texas.setPlayerRoles('initial') // 首局：Room.initialRoles（定庄+setOthers+锁座）；或 'rearrange'（仅 reArrangeRoles，须已有庄）
-texas.dealCards()
-// 上述会触发 onRolesAssigned / onDealCards（若已注册）
-// 批量 seat/remove 后：入座/离环时 Dealer 已各调过 reArrangeRoles；若仍希望「最后一次再推角色」，可再调 texas.reArrangeRoles()（不写入 RolesAssigned 缓冲，需自行读 dealer 上各席 role）
+const events1 = texas.setPlayerRoles('initial')
+// 首局：Room.initialRoles（定庄 + setOthers + lockSeats）
+// 或 'rearrange'（仅 reArrangeRoles，须已有庄）；可选 { buttonUserId }
+await interpret(events1) // 业务：落库 / WS；下同
+
+const events2 = texas.dealCards()
+// → HoleCardsDealt（byUserId 含全员手牌；出站前按 viewer 过滤）
+
+// 批量 seat/remove 后：Dealer 已各调 reArrangeRoles；可再 texas.reArrangeRoles() 统一推角色
+// （不缓冲 RolesAssigned，需自行读 dealer 各席 role）
 ```
 
 ### 4. 开始本手
 
 ```ts
-// 要求：至少两人 on-set、房间 seats_locked、controller.idle
-await texas.start()
-// 内部会下盲注并移交控制权到第一个行动玩家
+// 要求：至少 2 人 on-set、seats_locked、controller.idle
+const events3 = texas.start()
+// → HandStarted、BlindsPosted、PotUpdated…；队列入队首人 turn_handoff（尚无 TurnOffered）
+
+await drainAndConsumePendingFlow(texas, events3)
+// 生产：先解释 events3，再按节拍 applyPendingStageAdvance / flushPendingTurnHandoff 并 drain 新事件
+// 单测：texas.flushAllPendingFlowOps() 一次排空
+
+// 有待贴「入座大盲」队列时，用原子 API 替代 start + 循环 PostBigBlind：
+// texas.startPreflopWithJoiningBigBlinds([userId, ...])
 ```
 
-### 5. 轮到谁行动
+### 5. 玩家行动
 
-当前行动玩家：`texas.controller.activePlayer`。  
-该玩家可调用（均为 `async`，内部会校验合法行动并可能推进阶段/终局）：
+当前行动方：`texas.controller.activePlayer`（须已消费队头 `turn_handoff`，否则 `status` 非 `active`，`dispatchCommand` 会被拒）。
 
-- `check()` / `bet(amount)` / `call()` / `raise(amount)` / `fold()` / `allIn()`
+```ts
+const cmd: TableCommand = { type: 'Call', playerId: 2 }
+const events = texas.dispatchCommand(cmd)
+// 自愿：Fold | Check | Call | Bet | Raise | AllIn
+// 超时：FoldDueToTimeout | CheckDueToTimeout（须当前行动方）
+// 离场：FoldDueToLeave（须当前行动方；TurnEnded.reason === 'leave'）
+// 入座大盲：PostBigBlind（翻前、本街尚未入池；金额由 stakes 推导）
+
+await drainAndConsumePendingFlow(texas, events)
+```
 
-行动前可给每个玩家注册 `onPreAction`，用于推送「允许行动列表、加注区间」等（见下文监听）。
+轮到谁、允许哪些操作：解释缓冲中的 **`TurnOffered`**（`allowedActions`、`restrict`）。  
+行动结果：**`PlayerActed`** + 紧邻 **`PotUpdated`**；交权结束：**`TurnEnded`**。
 
 ### 6. 本手结束与清理
 
-终局时 `Controller` 会触发 `onGameEnd`（若已注册）。  
-之后业务侧通常：
+终局时缓冲会出现 **`HandEnded`**（`outcome`、`pokesRevealed`、`bestPokes` 等）。业务通常在解释该事件时：
+
+```ts
+const awarded = texas.settle() // pool.pay() → PotAwarded
+await interpret(awarded)
+
+texas.reset() // pool + dealer + controller → idle，unlockSeats
+// 下一手：reset → rotateRolesForNewHand → …局间 seat/reArrange… → lockSeats
+// → setPlayerRoles('rearrange')? → dealCards → start() 或 startPreflopWithJoiningBigBlinds
+```
+
+### 7. 业务侧最小循环（示意）
 
 ```ts
-texas.settle() // pool.pay()，按引擎规则分配边池
-texas.reset() // pool + dealer + controller 清理，controller → idle，并 unlockSeats
-// 下一手（示意）：reset(unlock) → rotateRolesForNewHand(移庄) → …局间 seat/reArrange… → lockSeats → setPlayerRoles('rearrange')? → dealCards → start()
+import type { Texas, TexasDomainEvent } from 'texas-poker-core'
+
+async function drainAndConsumePendingFlow(
+  texas: Texas,
+  firstBatch: TexasDomainEvent[]
+) {
+  await interpret(firstBatch)
+  while (texas.getPendingFlowOps().length > 0) {
+    await sleep(actionRequiredMs) // 产品节拍，Core 内无 sleep
+    const head = texas.getPendingFlowOps()[0]
+    const more =
+      head.kind === 'stage_advance'
+        ? texas.applyPendingStageAdvance()
+        : texas.flushPendingTurnHandoff()
+    await interpret(more)
+    if (head.kind === 'stage_advance' && texas.getPendingFlowOps().length > 0) {
+      await sleep(stageChangedMs)
+    }
+  }
+}
 ```
 
+单测可省略 `sleep`，在每次 `dispatchCommand` 后调用 **`texas.flushAllPendingFlowOps()`**。
+
 ---
 
-## 监听与回调（Texas）
+## 领域事件（`TexasDomainEvent`）
 
-| 方法              | 说明                                                                     |
-| ----------------- | ------------------------------------------------------------------------ |
-| `onError`         | 任意 `fail` / `TexasError` 抛出前回调                                    |
-| `onRolesAssigned` | `setPlayerRoles` 成功后，携带 `userId` / `role` / `actionIndex`          |
-| `onDealCards`     | `dealCards` 成功后，各玩家手牌（业务可据此推送私密牌）                   |
-| `onPreAction`     | 轮到玩家行动前（注册到所有当前 `Player`）                                |
-| `onAction`        | 玩家完成一次合法行动后（写库、广播；默认盲注行为可能不触发，以实现为准） |
-| `onGameStart`     | 本手 `controller.start()` 内、盲注与首回合开始前                         |
-| `onGameEnd`       | 一手结束，携带公牌、摊牌信息、`pokesRevealed` 等                         |
-| `onNextStage`     | 翻牌 / 转牌 / 河牌等阶段推进，携带本段新亮公牌                           |
+类型定义：`src/domain/handDomainEvents.ts`（包内从 `texas-poker-core` 导出 `TexasDomainEvent` / `HandDomainEvent`）。  
+本手事件均带 **`handId`**（`start` 时分配，如 `h1`）与单调 **`seq`**，供 `(matchId, handId, seq)` 幂等落库与回放。
 
-`Player` 上另有 `onPreAction` / `onAction`，适合按人注册。
+| 事件                     | 典型触发时机                                                                       |
+| ------------------------ | ---------------------------------------------------------------------------------- |
+| `RolesAssigned`          | `setPlayerRoles`                                                                   |
+| `HoleCardsDealt`         | `dealCards`                                                                        |
+| `HandStarted`            | `start` / `startPreflopWithJoiningBigBlinds`                                       |
+| `PostedJoiningBigBlinds` | 入座大盲汇总（`startPreflopWithJoiningBigBlinds` 恒一条；`PostBigBlind` 每次一条） |
+| `BlindsPosted`           | 桌 SB/BB 贴盲后                                                                    |
+| `PlayerActed`            | 自愿行动 / 超时行动（盲注路径不发）                                                |
+| `PotUpdated`             | 每次入池后（紧跟对应 `PlayerActed` 或盲注行）                                      |
+| `StageAdvanced`          | 消费 `stage_advance`：正常进街或跑马揭示                                           |
+| `TurnOffered`            | 消费 `turn_handoff`：`getControl` 后                                               |
+| `TurnEnded`              | 行动方交权结束（`reason`: `action` \| `timeout` \| `leave` 等）                    |
+| `PotAwarded`             | `settle()`                                                                         |
+| `HandEnded`              | 独赢弃牌或摊牌/跑马结束                                                            |
+
+**不再提供** `onGameEnd` / `onAction` / `onPreAction` 等实例回调；节奏由业务解释事件 + 消费 `pendingFlowOps` 完成。
+
+回放与持久化辅助：`toPersistedDomainEventRows`、`projectCompositeReadModel`、`interpret` 等见包导出与 [docs/replay-app-server-core-coordination.md](./docs/replay-app-server-core-coordination.md)。
+
+---
+
+## `TableCommand`（`dispatchCommand`）
+
+| `type`                                                | 说明                                                           |
+| ----------------------------------------------------- | -------------------------------------------------------------- |
+| `Fold` / `Check` / `Call` / `Bet` / `Raise` / `AllIn` | 自愿行动；`Bet`/`Raise` 带 `amount` / `additionalAmount`       |
+| `FoldDueToTimeout` / `CheckDueToTimeout`              | 计时到期；须当前行动方                                         |
+| `FoldDueToLeave`                                      | 当前行动方离场弃牌；可先 `canFoldDueToLeave(userId)`           |
+| `PostBigBlind`                                        | 翻前补入座大盲；可选 `allowWhenCurrentActor`（服务端可信队列） |
+
+JSON 解析：`parseTableCommandFromJson` / `parseTableCommandFromUnknown`。
+
+---
+
+## `Texas` 会话 API 速查
+
+| 方法                                                | 说明                                                       |
+| --------------------------------------------------- | ---------------------------------------------------------- |
+| `drainDomainEvents()`                               | 取出并清空事件缓冲（无副作用）                             |
+| `dispatchCommand(cmd)`                              | 玩家行动唯一推荐入口；返回本步事件                         |
+| `getPendingFlowOps()`                               | 流程队列快照（`stage_advance` \| `turn_handoff`）          |
+| `applyPendingStageAdvance()`                        | 消费队头进街/跑马；队头不对抛 `CTRL_FLOW_PENDING_MISMATCH` |
+| `flushPendingTurnHandoff()`                         | 消费队头交权 → `TurnOffered`；队头不对则静默 return        |
+| `flushAllPendingFlowOps()`                          | 无 sleep 排空队列（单测/批处理）                           |
+| `setPlayerRoles` / `dealCards` / `start` / `settle` | 返回本步领域事件；`start` 后须消费队列才有 `TurnOffered`   |
+| `startPreflopWithJoiningBigBlinds(ids)`             | 含入座大盲的原子开局                                       |
+| `rotateRolesForNewHand()`                           | `reset` 后局间移庄，不锁座                                 |
+| `reArrangeRoles()`                                  | 按庄位重算角色，不写 `RolesAssigned`                       |
+| `lockSeats` / `unlockSeats`                         | 显式锁座；`reset()` 会 `unlockSeats`                       |
+| `removePlayerByIdAsSystem`                          | 系统级踢人（可绕过 `seats_locked`）                        |
+| `canFoldDueToLeave` / `end`                         | 离场弃牌预判 / 强制结束到 `between_hands`                  |
 
 ---
 
@@ -150,8 +238,8 @@ texas.reset() // pool + dealer + controller 清理，controller → idle，并 u
 - `watch` / `watchById`：回观战（须 `seats_open`）
 - `remove` / `removeById`：离房；**仅观战（`hang`）锁座时也可离房**；**已入座**须 `seats_open`（**房主需业务先 `setOwner` 再 remove**）
 - `initialRoles`：定庄 + 盲位并 **lockSeats**；`rotateRoles`：局间移庄，**不** lock（下一手前由业务 `lockSeats`）
-- `lockSeats` / `unlockSeats`：显式锁/解锁（`Texas.reset()` 会在一手收尾后 `unlockSeats`）
-- `setOwner` / `setOwnerById` / `getBaseInfo` / `getPlayerById` / `getPlayersBySeatStatus` 等
+- `lockSeats` / `unlockSeats`：也可经 `texas.lockSeats()` / `texas.unlockSeats()`
+- `setOwner` / `setOwnerById` / `getPlayerById` / `getPlayersBySeatStatus` 等
 
 ---
 
@@ -159,18 +247,26 @@ texas.reset() // pool + dealer + controller 清理，controller → idle，并 u
 
 ```ts
 Texas.configureEngine({
-  // trace、仿真开关等，见 TexasEngineGlobalOptions
+  simulation: {
+    // 单测/集成脚本：如 immediateDefaultActionOnTurn、allowSingleSeatedPlayer 等
+  }
 })
-Texas.resetEngineContext()
+Texas.resetEngineContext() // jest.setup 已 beforeEach 调用
 ```
 
-导出中还包含牌型/阶段/行动枚举与工具函数（如 `formatterPoke`、`StageEnum`、`ActionTypeEnum`、`isFatalTexasErrorCode` 等），便于与业务错误分级、持久化字段对齐。
+导出中还包含牌型/阶段/行动枚举、读模型 reducer（`reduceCommunityBoardFromDomainEvents` 等）、`createStandardDeckPokes`、`rankSignatureToDisplayGroups`、`isFatalTexasErrorCode`、`texasErrorCategory` 等。
 
 ---
 
 ## 更多文档
 
-- 架构与事件化演进思路：`docs/architecture-events-orchestration.md`、`docs/roadmap-command-event-interpreter.md`
+| 文档                                                                                                     | 内容                                 |
+| -------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| [CORE_API.md](./CORE_API.md)                                                                             | 对外 API 与不变量摘要                |
+| [docs/integration-core-wish-event-flow.md](./docs/integration-core-wish-event-flow.md)                   | 与参考服务端的整局事件流、节拍、落库 |
+| [docs/refactor-maintainer-reference.md](./docs/refactor-maintainer-reference.md)                         | 队列语义与维护速查                   |
+| [docs/replay-app-server-core-coordination.md](./docs/replay-app-server-core-coordination.md)             | 回放磁带与 App/Server 配合           |
+| [docs/How to refactor to be side-effect-free/](./docs/How%20to%20refactor%20to%20be%20side-effect-free/) | 事件化架构与路线图                   |
 
 ---
 
@@ -620,4 +716,12 @@ reject modulo bias
 贴盲与 game start 原子化
 
 ## 1.4.29
-修复post bb玩家过牌导致的异常
+
+修复 post bb 玩家过牌导致的异常
+
+## 1.4.30
+
+同步 README 接入文档
+
+## 1.4.31
+增加跑马摊牌事件

package/dist/Controller/index.js

@@ -423,6 +423,7 @@ var Controller = /*#__PURE__*/function () {
       if (this.shouldShowDown()) {
         if (_classPrivateFieldGet(_hand, this).stage !== _stage.StageEnum.RIVER) {
           _classPrivateFieldSet(_runoutMode, this, true);
+          _assertClassBrand(_Controller_brand, this, _emitRunoutHandsRevealed).call(this);
           var from = _classPrivateFieldGet(_hand, this).stage;
           // 计算pending几次跑马
           while (from !== _stage.StageEnum.RIVER) {
@@ -619,6 +620,21 @@ function _everyPlayerNonActionableForRound() {
     return !pl.actionable();
   });
 }
+/** 进入跑马路：对仍在局内的玩家同步亮底牌（在 `stage_advance` 入队前）。 */
+function _emitRunoutHandsRevealed() {
+  var revealedHands = _classPrivateFieldGet(_dealer, this).getPlayersStillInGame().map(function (player) {
+    return {
+      userId: player.getUserInfo().id,
+      handPokes: player.getHandPokes()
+    };
+  });
+  _classPrivateFieldGet(_handEvents, this).push({
+    type: 'RunoutHandsRevealed',
+    payload: _objectSpread(_objectSpread({}, _assertClassBrand(_Controller_brand, this, _eventMeta).call(this)), {}, {
+      revealedHands: revealedHands
+    })
+  });
+}
 /** 河牌摊牌：`settle` + `end` + `HandEnded(showdown)`（与跑马路最后一跳共用）。 */
 function _emitShowdownHandEnded() {
   _assertClassBrand(_Controller_brand, this, _settle).call(this);

package/dist/engine/domainEventReadModel.js

@@ -14,6 +14,7 @@ exports.reduceLastHoleCardsDealtFromDomainEvents = reduceLastHoleCardsDealtFromD
 exports.reduceLastPostedBigBlindFromDomainEvents = reduceLastPostedBigBlindFromDomainEvents;
 exports.reduceLastPotAwardedFromDomainEvents = reduceLastPotAwardedFromDomainEvents;
 exports.reduceLastRolesAssignedFromDomainEvents = reduceLastRolesAssignedFromDomainEvents;
+exports.reduceLastRunoutHandsRevealedFromDomainEvents = reduceLastRunoutHandsRevealedFromDomainEvents;
 exports.reduceLastStageAdvancedFromDomainEvents = reduceLastStageAdvancedFromDomainEvents;
 exports.reduceLastTurnOfferedFromDomainEvents = reduceLastTurnOfferedFromDomainEvents;
 exports.reducePlayerActedTrailFromDomainEvents = reducePlayerActedTrailFromDomainEvents;
@@ -323,14 +324,45 @@ function reduceLastStageAdvancedFromDomainEvents(events) {
   return last;
 }
 
-/** 磁带中首条 `HandStarted`（本手锚点）。 */
+/** 本批中**最后一条** `RunoutHandsRevealed`（跑马摊牌；每手至多一条）。 */
 
-function reduceFirstHandStartedFromDomainEvents(events) {
+function reduceLastRunoutHandsRevealedFromDomainEvents(events) {
+  var last = null;
   var _iterator11 = _createForOfIteratorHelper(events),
     _step11;
   try {
     for (_iterator11.s(); !(_step11 = _iterator11.n()).done;) {
       var e = _step11.value;
+      if (e.type === 'RunoutHandsRevealed') {
+        var p = e.payload;
+        last = {
+          handId: p.handId,
+          seq: p.seq,
+          revealedHands: p.revealedHands.map(function (row) {
+            return {
+              userId: row.userId,
+              handPokes: row.handPokes
+            };
+          })
+        };
+      }
+    }
+  } catch (err) {
+    _iterator11.e(err);
+  } finally {
+    _iterator11.f();
+  }
+  return last;
+}
+
+/** 磁带中首条 `HandStarted`（本手锚点）。 */
+
+function reduceFirstHandStartedFromDomainEvents(events) {
+  var _iterator12 = _createForOfIteratorHelper(events),
+    _step12;
+  try {
+    for (_iterator12.s(); !(_step12 = _iterator12.n()).done;) {
+      var e = _step12.value;
       if (e.type === 'HandStarted') {
         return {
           handId: e.payload.handId,
@@ -339,9 +371,9 @@ function reduceFirstHandStartedFromDomainEvents(events) {
       }
     }
   } catch (err) {
-    _iterator11.e(err);
+    _iterator12.e(err);
   } finally {
-    _iterator11.f();
+    _iterator12.f();
   }
   return null;
 }
@@ -356,11 +388,11 @@ function reduceHandIdFromFirstHandStarted(events) {
 
 function reduceTurnEndedTrailFromDomainEvents(events) {
   var rows = [];
-  var _iterator12 = _createForOfIteratorHelper(events),
-    _step12;
+  var _iterator13 = _createForOfIteratorHelper(events),
+    _step13;
   try {
-    for (_iterator12.s(); !(_step12 = _iterator12.n()).done;) {
-      var e = _step12.value;
+    for (_iterator13.s(); !(_step13 = _iterator13.n()).done;) {
+      var e = _step13.value;
       if (e.type === 'TurnEnded') {
         var _e$payload4 = e.payload,
           seq = _e$payload4.seq,
@@ -374,9 +406,9 @@ function reduceTurnEndedTrailFromDomainEvents(events) {
       }
     }
   } catch (err) {
-    _iterator12.e(err);
+    _iterator13.e(err);
   } finally {
-    _iterator12.f();
+    _iterator13.f();
   }
   rows.sort(function (a, b) {
     return a.seq - b.seq;
@@ -388,11 +420,11 @@ function reduceTurnEndedTrailFromDomainEvents(events) {
 
 function reduceLastPostedBigBlindFromDomainEvents(events) {
   var last = null;
-  var _iterator13 = _createForOfIteratorHelper(events),
-    _step13;
+  var _iterator14 = _createForOfIteratorHelper(events),
+    _step14;
   try {
-    for (_iterator13.s(); !(_step13 = _iterator13.n()).done;) {
-      var e = _step13.value;
+    for (_iterator14.s(); !(_step14 = _iterator14.n()).done;) {
+      var e = _step14.value;
       if (e.type === 'PostedJoiningBigBlinds') {
         var posts = e.payload.posts;
         if (posts.length === 0) continue;
@@ -408,9 +440,9 @@ function reduceLastPostedBigBlindFromDomainEvents(events) {
       }
     }
   } catch (err) {
-    _iterator13.e(err);
+    _iterator14.e(err);
   } finally {
-    _iterator13.f();
+    _iterator14.f();
   }
   return last;
 }
@@ -419,11 +451,11 @@ function reduceLastPostedBigBlindFromDomainEvents(events) {
 
 function reduceLastRolesAssignedFromDomainEvents(events) {
   var last = null;
-  var _iterator14 = _createForOfIteratorHelper(events),
-    _step14;
+  var _iterator15 = _createForOfIteratorHelper(events),
+    _step15;
   try {
-    for (_iterator14.s(); !(_step14 = _iterator14.n()).done;) {
-      var e = _step14.value;
+    for (_iterator15.s(); !(_step15 = _iterator15.n()).done;) {
+      var e = _step15.value;
       if (e.type === 'RolesAssigned') {
         var p = e.payload;
         last = {
@@ -441,9 +473,9 @@ function reduceLastRolesAssignedFromDomainEvents(events) {
       }
     }
   } catch (err) {
-    _iterator14.e(err);
+    _iterator15.e(err);
   } finally {
-    _iterator14.f();
+    _iterator15.f();
   }
   return last;
 }
@@ -452,11 +484,11 @@ function reduceLastRolesAssignedFromDomainEvents(events) {
 
 function reduceLastHoleCardsDealtFromDomainEvents(events) {
   var last = null;
-  var _iterator15 = _createForOfIteratorHelper(events),
-    _step15;
+  var _iterator16 = _createForOfIteratorHelper(events),
+    _step16;
   try {
-    for (_iterator15.s(); !(_step15 = _iterator15.n()).done;) {
-      var e = _step15.value;
+    for (_iterator16.s(); !(_step16 = _iterator16.n()).done;) {
+      var e = _step16.value;
       if (e.type === 'HoleCardsDealt') {
         var _e$payload5 = e.payload,
           handId = _e$payload5.handId,
@@ -477,9 +509,9 @@ function reduceLastHoleCardsDealtFromDomainEvents(events) {
       }
     }
   } catch (err) {
-    _iterator15.e(err);
+    _iterator16.e(err);
   } finally {
-    _iterator15.f();
+    _iterator16.f();
   }
   return last;
 }

package/dist/engine/index.js

@@ -201,6 +201,12 @@ Object.defineProperty(exports, "reduceLastRolesAssignedFromDomainEvents", {
     return _domainEventReadModel.reduceLastRolesAssignedFromDomainEvents;
   }
 });
+Object.defineProperty(exports, "reduceLastRunoutHandsRevealedFromDomainEvents", {
+  enumerable: true,
+  get: function get() {
+    return _domainEventReadModel.reduceLastRunoutHandsRevealedFromDomainEvents;
+  }
+});
 Object.defineProperty(exports, "reduceLastStageAdvancedFromDomainEvents", {
   enumerable: true,
   get: function get() {

package/dist/index.js

@@ -71,6 +71,7 @@ var _exportNames = {
   reduceLastPotAwardedFromDomainEvents: true,
   reduceLastBlindsPostedFromDomainEvents: true,
   reduceLastStageAdvancedFromDomainEvents: true,
+  reduceLastRunoutHandsRevealedFromDomainEvents: true,
   reduceFirstHandStartedFromDomainEvents: true,
   reduceHandIdFromFirstHandStarted: true,
   reduceTurnEndedTrailFromDomainEvents: true,
@@ -604,6 +605,12 @@ Object.defineProperty(exports, "reduceLastRolesAssignedFromDomainEvents", {
     return _engine.reduceLastRolesAssignedFromDomainEvents;
   }
 });
+Object.defineProperty(exports, "reduceLastRunoutHandsRevealedFromDomainEvents", {
+  enumerable: true,
+  get: function get() {
+    return _engine.reduceLastRunoutHandsRevealedFromDomainEvents;
+  }
+});
 Object.defineProperty(exports, "reduceLastStageAdvancedFromDomainEvents", {
   enumerable: true,
   get: function get() {

package/dist/replay/projectCompositeReadModel.js

@@ -19,6 +19,7 @@ function projectCompositeReadModel(events) {
     pot: (0, _domainEventReadModel.reducePotFromDomainEvents)(events),
     communityBoard: (0, _domainEventReadModel.reduceCommunityBoardFromDomainEvents)(events),
     lastStageAdvanced: (0, _domainEventReadModel.reduceLastStageAdvancedFromDomainEvents)(events),
+    lastRunoutHandsRevealed: (0, _domainEventReadModel.reduceLastRunoutHandsRevealedFromDomainEvents)(events),
     lastTurnOffered: (0, _domainEventReadModel.reduceLastTurnOfferedFromDomainEvents)(events),
     playerActedTrail: (0, _domainEventReadModel.reducePlayerActedTrailFromDomainEvents)(events),
     turnEndedTrail: (0, _domainEventReadModel.reduceTurnEndedTrailFromDomainEvents)(events),

package/dist/simulateFiftyDealsReport.js

@@ -0,0 +1,194 @@
+"use strict";
+
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+var fs = _interopRequireWildcard(require("node:fs"));
+var path = _interopRequireWildcard(require("node:path"));
+var _Texas = _interopRequireDefault(require("./Texas"));
+var _core = require("./Deck/core");
+var _constant = require("./Player/constant");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != _typeof(e) && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+function _toConsumableArray(r) { return _arrayWithoutHoles(r) || _iterableToArray(r) || _unsupportedIterableToArray(r) || _nonIterableSpread(); }
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _iterableToArray(r) { if ("undefined" != typeof Symbol && null != r[Symbol.iterator] || null != r["@@iterator"]) return Array.from(r); }
+function _arrayWithoutHoles(r) { if (Array.isArray(r)) return _arrayLikeToArray(r); }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; } /**
+ * 模拟 wish 业务层发牌流程（5 人 × 50 局），输出 Markdown 到仓库根目录。
+ *
+ * 首局（useCase）：setPlayerRoles('initial') → dealCards()
+ * 后续局（eventBinder + HandEnded）：unlockSeats → rotateRolesForNewHand →
+ *   onLock: reset + lockSeats → setPlayerRoles('rearrange') → dealCards()
+ */
+var PLAYER_COUNT = 5;
+var DEAL_COUNT = 50;
+var OUTPUT_FILE = path.join(__dirname, '..', 'DEAL_SIMULATION_5P_50H.md');
+function fmtOne(poke) {
+  return (0, _core.formatterPoke)([poke]);
+}
+function fmt(pokes) {
+  return pokes.length ? (0, _core.formatterPoke)(_toConsumableArray(pokes)) : '—';
+}
+function buildDealSequenceLabels(shuffledDeck, playerCount) {
+  var deck = _toConsumableArray(shuffledDeck);
+  var labels = [];
+  var idx = 0;
+  for (var round = 0; round < 2; round++) {
+    for (var seat = 0; seat < playerCount; seat++) {
+      labels.push("#".concat(idx + 1, " \u624B\u724C \u5EA7\u4F4D").concat(seat + 1, " \u7B2C").concat(round + 1, "\u5F20 \u2192 ").concat(fmt([deck[idx]])));
+      idx++;
+    }
+  }
+  labels.push("#".concat(idx + 1, " \u70E7\u724C(flop\u524D) \u2192 ").concat(fmt([deck[idx]])));
+  idx++;
+  for (var i = 0; i < 3; i++) {
+    labels.push("#".concat(idx + 1, " \u7FFB\u724C").concat(i + 1, " \u2192 ").concat(fmt([deck[idx]])));
+    idx++;
+  }
+  labels.push("#".concat(idx + 1, " \u70E7\u724C(turn\u524D) \u2192 ").concat(fmt([deck[idx]])));
+  idx++;
+  labels.push("#".concat(idx + 1, " \u8F6C\u724C \u2192 ").concat(fmt([deck[idx]])));
+  idx++;
+  labels.push("#".concat(idx + 1, " \u70E7\u724C(river\u524D) \u2192 ").concat(fmt([deck[idx]])));
+  idx++;
+  labels.push("#".concat(idx + 1, " \u6CB3\u724C \u2192 ").concat(fmt([deck[idx]])));
+  idx++;
+  while (idx < deck.length) {
+    labels.push("#".concat(idx + 1, " \u672A\u53D1\u5269\u4F59 \u2192 ").concat(fmt([deck[idx]])));
+    idx++;
+  }
+  return labels;
+}
+function setupTexas() {
+  var texas = new _Texas.default({
+    lowestBetAmount: 20,
+    maximumCountOfPlayers: PLAYER_COUNT,
+    initialChips: 2000,
+    user: {
+      id: 1,
+      name: 'P1'
+    }
+  });
+  var players = [texas.room.owner, texas.createPlayer({
+    id: 2,
+    name: 'P2'
+  }), texas.createPlayer({
+    id: 3,
+    name: 'P3'
+  }), texas.createPlayer({
+    id: 4,
+    name: 'P4'
+  }), texas.createPlayer({
+    id: 5,
+    name: 'P5'
+  })];
+  for (var _i = 0, _players = players; _i < _players.length; _i++) {
+    var p = _players[_i];
+    if (p !== texas.room.owner) {
+      texas.room.join(p);
+    }
+    texas.room.seat(p);
+  }
+  return texas;
+}
+function runFirstHandDeal(texas) {
+  texas.setPlayerRoles('initial');
+  texas.dealCards();
+}
+function runNextHandDeal(texas) {
+  texas.unlockSeats();
+  texas.rotateRolesForNewHand();
+  texas.reset();
+  texas.lockSeats();
+  texas.setPlayerRoles('rearrange');
+  texas.dealCards();
+}
+function main() {
+  var texas = setupTexas();
+  var sections = [];
+  sections.push('# 5 人桌 × 50 次发牌模拟');
+  sections.push('');
+  sections.push('> 生成时间：' + new Date().toISOString());
+  sections.push('> 引擎：`texas-poker-core` `Deck#dealCards`（每次发牌前 Fisher–Yates 洗牌）');
+  sections.push('');
+  sections.push('## 业务层发牌流程（wish_mono_server）');
+  sections.push('');
+  sections.push('### 首局（`useCase.ts` → `#runStartFlow`）');
+  sections.push('');
+  sections.push('1. `texas.setPlayerRoles()`（默认 `initial`：定庄 + 锁座）');
+  sections.push('2. `texas.dealCards()` → `HoleCardsDealt`');
+  sections.push('3. `texas.start()`（本模拟仅记录发牌，不 `start`）');
+  sections.push('');
+  sections.push('### 后续局（`eventBinder.ts` 局间钩子 + `HandEnded` 收尾）');
+  sections.push('');
+  sections.push('1. 上一手结束：`texas.unlockSeats()` → `texas.rotateRolesForNewHand()`');
+  sections.push('2. 倒计时 lock：`texas.reset()` → `texas.lockSeats()`');
+  sections.push("3. `onAssignRoles`：`texas.setPlayerRoles('rearrange')`");
+  sections.push('4. `onDeal`：`texas.dealCards()`');
+  sections.push('5. `onStart`：`texas.startPreflopWithJoiningBigBlinds(...)`（本模拟省略）');
+  sections.push('');
+  sections.push('---');
+  sections.push('');
+  var _loop = function _loop() {
+    if (hand === 1) {
+      runFirstHandDeal(texas);
+    } else {
+      runNextHandDeal(texas);
+    }
+    var _texas$dealer$getPoke = texas.dealer.getPokes(),
+      commonPokes = _texas$dealer$getPoke.commonPokes,
+      handPokes = _texas$dealer$getPoke.handPokes;
+    var shuffledDeck = _toConsumableArray(texas.dealer.deck.getCards());
+    var playersInOrder = texas.dealer.getPlayersByActionSequence();
+    var dealPath = buildDealSequenceLabels(shuffledDeck, PLAYER_COUNT);
+    sections.push("## \u7B2C ".concat(hand, " \u6B21\u53D1\u724C").concat(hand === 1 ? '（首局 · initial）' : '（后续局 · rearrange）'));
+    sections.push('');
+    sections.push('### 1. 公牌（5 张，含烧牌后亮出的 flop/turn/river）');
+    sections.push('');
+    sections.push('```');
+    sections.push(fmt(commonPokes));
+    sections.push('```');
+    sections.push('');
+    sections.push('### 2. 各玩家手牌（按行动序，从庄家下家起）');
+    sections.push('');
+    sections.push('| 座位序 | userId | 昵称 | 角色 | 手牌 |');
+    sections.push('| ------ | ------ | ---- | ---- | ---- |');
+    playersInOrder.forEach(function (player, seatIdx) {
+      var _roleMap$get, _handPokes$seatIdx;
+      var _player$getUserInfo = player.getUserInfo(),
+        id = _player$getUserInfo.id,
+        name = _player$getUserInfo.name;
+      var role = player.getRole();
+      var roleLabel = role ? (_roleMap$get = _constant.roleMap.get(role)) !== null && _roleMap$get !== void 0 ? _roleMap$get : role : '—';
+      var hole = (_handPokes$seatIdx = handPokes[seatIdx]) !== null && _handPokes$seatIdx !== void 0 ? _handPokes$seatIdx : [];
+      sections.push("| ".concat(seatIdx + 1, " | ").concat(id, " | ").concat(name, " | ").concat(roleLabel, " | ").concat(fmt(hole), " |"));
+    });
+    sections.push('');
+    sections.push('### 3. 全部 52 张底牌（本次洗牌后牌堆顺序，自顶向下发）');
+    sections.push('');
+    sections.push('```');
+    sections.push(shuffledDeck.map(function (p, i) {
+      return "".concat(String(i + 1).padStart(2, ' '), ". ").concat(fmtOne(p), " (").concat(p, ")");
+    }).join('\n'));
+    sections.push('```');
+    sections.push('');
+    sections.push('<details>');
+    sections.push('<summary>发牌路径标注（含烧牌）</summary>');
+    sections.push('');
+    sections.push('```');
+    sections.push(dealPath.join('\n'));
+    sections.push('```');
+    sections.push('');
+    sections.push('</details>');
+    sections.push('');
+    sections.push('---');
+    sections.push('');
+  };
+  for (var hand = 1; hand <= DEAL_COUNT; hand++) {
+    _loop();
+  }
+  fs.writeFileSync(OUTPUT_FILE, sections.join('\n'), 'utf8');
+  console.log("Wrote ".concat(DEAL_COUNT, " deals to ").concat(OUTPUT_FILE));
+}
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "texas-poker-core",
-  "version": "1.4.29",
+  "version": "1.4.31",
   "description": "德州扑克核心功能",
   "main": "dist/index.js",
   "types": "types/index.d.ts",

package/types/domain/handDomainEvents.d.ts

@@ -15,6 +15,11 @@ export type HandEventMeta = {
     handId: string;
     seq: number;
 };
+/** 跑马开始时对仍在摊牌中的玩家亮出的底牌（不含 rank；牌力由客户端用 core 自算）。 */
+export type RunoutRevealedHand = {
+    userId: number;
+    handPokes: Poke[];
+};
 /**
  * 本手领域事件（无业务 callback；由 {@link Texas#dispatchCommand} 等同步返回，或 {@link Texas#drainDomainEvents} / Controller 缓冲取出）。
  * 含 **分配角色 → 发洞牌 → 贴盲与街道** 的完整磁带，便于「只重放某一手」时按 `handId` 过滤即可。
@@ -95,6 +100,16 @@ export type HandDomainEvent = {
         pokesRevealedThisStep: Poke[];
         advanceKind: 'betting_round_complete' | 'runout_reveal';
     };
+}
+/**
+ * 进入跑马路时同步发出（在首条 `StageAdvanced(runout_reveal)` 入队之前）。
+ * 业务层映射为 WS `runout-hands-revealed`，不受 `pendingFlowOps` pacing 影响。
+ */
+ | {
+    type: 'RunoutHandsRevealed';
+    payload: HandEventMeta & {
+        revealedHands: RunoutRevealedHand[];
+    };
 } | {
     type: 'TurnOffered';
     payload: HandEventMeta & {

package/types/engine/domainEventReadModel.d.ts

@@ -87,6 +87,16 @@ export type StageAdvancedReadModel = Readonly<{
     advanceKind: 'betting_round_complete' | 'runout_reveal';
 }>;
 export declare function reduceLastStageAdvancedFromDomainEvents(events: readonly TexasDomainEvent[]): StageAdvancedReadModel | null;
+/** 本批中**最后一条** `RunoutHandsRevealed`（跑马摊牌；每手至多一条）。 */
+export type RunoutHandsRevealedReadModel = Readonly<{
+    handId: string;
+    seq: number;
+    revealedHands: ReadonlyArray<Readonly<{
+        userId: number;
+        handPokes: readonly Poke[];
+    }>>;
+}>;
+export declare function reduceLastRunoutHandsRevealedFromDomainEvents(events: readonly TexasDomainEvent[]): RunoutHandsRevealedReadModel | null;
 /** 磁带中首条 `HandStarted`（本手锚点）。 */
 export type HandStartedReadModel = Readonly<{
     handId: string;

package/types/engine/index.d.ts

@@ -9,7 +9,7 @@ export type { ApplyTableCommandResult } from './applyTableCommand';
 export { pendingFlowOpsAllowVoluntaryDispatch, peekPendingFlowOp, simulateDequeuePendingHeadIfMatches } from './pendingFlowReadModel';
 export { captureSeatUserIdsInActionOrder } from './dealerRingReadModel';
 export { applyTableCommand, applyTableCommandThenFlushAllPendingFlowOps } from './applyTableCommand';
-export type { BlindsPostedReadModel, HandEndedReadModel, HandStartedReadModel, HoleCardsDealtReadModel, PlayerActedEntry, PostedBigBlindReadModel, PotAwardedReadModel, PotContributionReadModel, RolesAssignedReadModel, StageAdvancedReadModel, TurnEndedEntry, TurnOfferReadModel } from './domainEventReadModel';
-export { flatConcatDomainEvents, filterDomainEventsByHandId, reducePotFromDomainEvents, reduceLastTurnOfferedFromDomainEvents, reducePlayerActedTrailFromDomainEvents, reduceCommunityBoardFromDomainEvents, reduceLastHandEndedFromDomainEvents, reduceLastPotAwardedFromDomainEvents, reduceLastBlindsPostedFromDomainEvents, reduceLastStageAdvancedFromDomainEvents, reduceFirstHandStartedFromDomainEvents, reduceHandIdFromFirstHandStarted, reduceTurnEndedTrailFromDomainEvents, reduceLastPostedBigBlindFromDomainEvents, reduceLastRolesAssignedFromDomainEvents, reduceLastHoleCardsDealtFromDomainEvents } from './domainEventReadModel';
+export type { BlindsPostedReadModel, HandEndedReadModel, HandStartedReadModel, HoleCardsDealtReadModel, PlayerActedEntry, PostedBigBlindReadModel, PotAwardedReadModel, PotContributionReadModel, RolesAssignedReadModel, StageAdvancedReadModel, RunoutHandsRevealedReadModel, TurnEndedEntry, TurnOfferReadModel } from './domainEventReadModel';
+export { flatConcatDomainEvents, filterDomainEventsByHandId, reducePotFromDomainEvents, reduceLastTurnOfferedFromDomainEvents, reducePlayerActedTrailFromDomainEvents, reduceCommunityBoardFromDomainEvents, reduceLastHandEndedFromDomainEvents, reduceLastPotAwardedFromDomainEvents, reduceLastBlindsPostedFromDomainEvents, reduceLastStageAdvancedFromDomainEvents, reduceLastRunoutHandsRevealedFromDomainEvents, reduceFirstHandStartedFromDomainEvents, reduceHandIdFromFirstHandStarted, reduceTurnEndedTrailFromDomainEvents, reduceLastPostedBigBlindFromDomainEvents, reduceLastRolesAssignedFromDomainEvents, reduceLastHoleCardsDealtFromDomainEvents } from './domainEventReadModel';
 export type { HandReduceProjection, FoldOrCheckTableCommand, VoluntaryTableCommand } from './handReducer';
 export { captureHandReduceProjection, applyVoluntaryTableCommand, applyFoldOrCheckCommand, isVoluntaryTableCommand } from './handReducer';

package/types/index.d.ts

@@ -23,12 +23,12 @@ type TexasErrorCodeLegacy, CurrentHand };
 export type { TexasDomainEvent, HandDomainEvent, CreateRoomInputArgs } from './Texas';
 export type { TableCommand } from './domain/tableCommand';
 export { parseTableCommandFromJson, parseTableCommandFromUnknown } from './domain/tableCommandParse';
-export type { TurnEndedReason, HandEventMeta } from './domain/handDomainEvents';
+export type { TurnEndedReason, HandEventMeta, RunoutRevealedHand } from './domain/handDomainEvents';
 export type { OrchestrationCtx, DomainEventHandler } from './orchestration/interpret';
 export { interpret } from './orchestration/interpret';
 export { createDefaultPipelineHandlers, defaultPipelineOrdered } from './orchestration/defaultPipeline';
-export { dispatchCommandAndInterpret, interpretTableEvents, flushAllPendingFlowOpsAndInterpret, captureTableSnapshot, applyTableCommand, applyTableCommandThenFlushAllPendingFlowOps, flatConcatDomainEvents, filterDomainEventsByHandId, reducePotFromDomainEvents, reduceLastTurnOfferedFromDomainEvents, reducePlayerActedTrailFromDomainEvents, reduceCommunityBoardFromDomainEvents, reduceLastHandEndedFromDomainEvents, reduceLastPotAwardedFromDomainEvents, reduceLastBlindsPostedFromDomainEvents, reduceLastStageAdvancedFromDomainEvents, reduceFirstHandStartedFromDomainEvents, reduceHandIdFromFirstHandStarted, reduceTurnEndedTrailFromDomainEvents, reduceLastPostedBigBlindFromDomainEvents, reduceLastRolesAssignedFromDomainEvents, reduceLastHoleCardsDealtFromDomainEvents, captureHandReduceProjection, applyVoluntaryTableCommand, applyFoldOrCheckCommand, isVoluntaryTableCommand, pendingFlowOpsAllowVoluntaryDispatch, peekPendingFlowOp, simulateDequeuePendingHeadIfMatches, captureSeatUserIdsInActionOrder, CANONICAL_TABLE_SESSION_JSON_SCHEMA_VERSION, cloneTableSnapshot, parseCanonicalTableSessionFromJson, reduceCanonicalTableSession, TABLE_STATE_V1_SCHEMA_VERSION, assertTableMatchesStateV1Snapshot, freezeTableStateV1FromLive, reduceCanonicalSessionToTableStateV1, applyTableCommandWithStateV1 } from './engine';
-export type { TableSnapshot, TablePlayerSnapshot, BootstrapInstruction, CanonicalTableSession, CommandStepInstruction, ReduceCanonicalTableSessionResult, TableStateV1, ApplyTableCommandWithStateV1Result, ApplyTableCommandResult, BlindsPostedReadModel, HandEndedReadModel, HandStartedReadModel, HoleCardsDealtReadModel, PlayerActedEntry, PostedBigBlindReadModel, PotAwardedReadModel, PotContributionReadModel, RolesAssignedReadModel, StageAdvancedReadModel, TurnEndedEntry, TurnOfferReadModel, HandReduceProjection, FoldOrCheckTableCommand, VoluntaryTableCommand } from './engine';
+export { dispatchCommandAndInterpret, interpretTableEvents, flushAllPendingFlowOpsAndInterpret, captureTableSnapshot, applyTableCommand, applyTableCommandThenFlushAllPendingFlowOps, flatConcatDomainEvents, filterDomainEventsByHandId, reducePotFromDomainEvents, reduceLastTurnOfferedFromDomainEvents, reducePlayerActedTrailFromDomainEvents, reduceCommunityBoardFromDomainEvents, reduceLastHandEndedFromDomainEvents, reduceLastPotAwardedFromDomainEvents, reduceLastBlindsPostedFromDomainEvents, reduceLastStageAdvancedFromDomainEvents, reduceLastRunoutHandsRevealedFromDomainEvents, reduceFirstHandStartedFromDomainEvents, reduceHandIdFromFirstHandStarted, reduceTurnEndedTrailFromDomainEvents, reduceLastPostedBigBlindFromDomainEvents, reduceLastRolesAssignedFromDomainEvents, reduceLastHoleCardsDealtFromDomainEvents, captureHandReduceProjection, applyVoluntaryTableCommand, applyFoldOrCheckCommand, isVoluntaryTableCommand, pendingFlowOpsAllowVoluntaryDispatch, peekPendingFlowOp, simulateDequeuePendingHeadIfMatches, captureSeatUserIdsInActionOrder, CANONICAL_TABLE_SESSION_JSON_SCHEMA_VERSION, cloneTableSnapshot, parseCanonicalTableSessionFromJson, reduceCanonicalTableSession, TABLE_STATE_V1_SCHEMA_VERSION, assertTableMatchesStateV1Snapshot, freezeTableStateV1FromLive, reduceCanonicalSessionToTableStateV1, applyTableCommandWithStateV1 } from './engine';
+export type { TableSnapshot, TablePlayerSnapshot, BootstrapInstruction, CanonicalTableSession, CommandStepInstruction, ReduceCanonicalTableSessionResult, TableStateV1, ApplyTableCommandWithStateV1Result, ApplyTableCommandResult, BlindsPostedReadModel, HandEndedReadModel, HandStartedReadModel, HoleCardsDealtReadModel, PlayerActedEntry, PostedBigBlindReadModel, PotAwardedReadModel, PotContributionReadModel, RolesAssignedReadModel, StageAdvancedReadModel, RunoutHandsRevealedReadModel, TurnEndedEntry, TurnOfferReadModel, HandReduceProjection, FoldOrCheckTableCommand, VoluntaryTableCommand } from './engine';
 export type { PersistedDomainEventRow, DomainEventStore, DomainEventsCompositeReadModel, DomainEventTapeValidationIssue, VerifyCanonicalAgainstTapeResult, VerifyCanonicalAgainstTapeCompactResult, ReplayVerifyExitPolicy, VerifyCanonicalDiffContext, VerifyEventSignature } from './replay';
 export { toPersistedDomainEventRows, createInMemoryDomainEventStore, domainEventsFromPersistedRows, validatePersistedDomainEventRows, assertPersistedDomainEventRows, summarizePersistedDomainEventRows, verifyCanonicalSessionAgainstPersistedRows, toCompactVerifyCanonicalAgainstTapeResult, resolveReplayVerifyExitCode, createAppendDomainEventsHandler, projectCompositeReadModel } from './replay';
 export type { PreAction } from './gameContracts';

package/types/replay/projectCompositeReadModel.d.ts

@@ -1,6 +1,6 @@
 import type { Poke } from '../Deck/constant';
 import type { TexasDomainEvent } from '../domain/handDomainEvents';
-import type { TurnEndedEntry, PlayerActedEntry, HandEndedReadModel, TurnOfferReadModel, PotAwardedReadModel, HandStartedReadModel, BlindsPostedReadModel, RolesAssignedReadModel, StageAdvancedReadModel, HoleCardsDealtReadModel, PostedBigBlindReadModel, PotContributionReadModel } from '../engine/domainEventReadModel';
+import type { TurnEndedEntry, PlayerActedEntry, HandEndedReadModel, TurnOfferReadModel, PotAwardedReadModel, HandStartedReadModel, BlindsPostedReadModel, RolesAssignedReadModel, StageAdvancedReadModel, HoleCardsDealtReadModel, PostedBigBlindReadModel, PotContributionReadModel, RunoutHandsRevealedReadModel } from '../engine/domainEventReadModel';
 /**
  * 单条磁带上的**只读复合投影**（阶段 6 向 `reduce(apply)` 过渡的读侧聚合；**非**完整状态机）。
  * 供回放对拍、机器人读盘、接入方一条 API 取多视角。
@@ -13,6 +13,7 @@ export type DomainEventsCompositeReadModel = Readonly<{
     pot: PotContributionReadModel;
     communityBoard: readonly Poke[];
     lastStageAdvanced: StageAdvancedReadModel | null;
+    lastRunoutHandsRevealed: RunoutHandsRevealedReadModel | null;
     lastTurnOffered: TurnOfferReadModel | null;
     playerActedTrail: readonly PlayerActedEntry[];
     turnEndedTrail: readonly TurnEndedEntry[];

package/types/simulateFiftyDealsReport.d.ts

@@ -0,0 +1 @@
+export {};