texas-poker-core 1.4.30 → 1.4.31

package/README.md

@@ -30,7 +30,7 @@ npm install texas-poker-core
 | `Texas`      | 会话门面：`setPlayerRoles` / `dealCards` / `start` / `dispatchCommand` / `drainDomainEvents` / 消费 `pendingFlowOps` / `reset` 等 |
 | `Room`       | 成员加入/观战/入座/离座、`initialRoles`（末 `lockSeats`）/ `rotateRoles`（不锁座）、`RoomStatus`（`seats_open` / `seats_locked`） |
 | `Dealer`     | 盲注、庄家、角色顺序、发牌（通常经 `Texas` / `Room` 访问）                                                                        |
-| `Controller` | 一手牌 `HandLifecycle`、当前街 `stage`、`activePlayer`、事件缓冲与 `pendingFlowOps` 队列                                            |
+| `Controller` | 一手牌 `HandLifecycle`、当前街 `stage`、`activePlayer`、事件缓冲与 `pendingFlowOps` 队列                                          |
 | `Pool`       | 奖池与支付（`texas.settle()` 时 `pool.pay()`，并缓冲 `PotAwarded`）                                                               |
 | `Player`     | 单座筹码、手牌、允许行动集合；**勿**直接调 `check`/`bet`/…，统一经 `Texas#dispatchCommand`                                        |
 
@@ -177,20 +177,20 @@ async function drainAndConsumePendingFlow(
 类型定义：`src/domain/handDomainEvents.ts`（包内从 `texas-poker-core` 导出 `TexasDomainEvent` / `HandDomainEvent`）。  
 本手事件均带 **`handId`**（`start` 时分配，如 `h1`）与单调 **`seq`**，供 `(matchId, handId, seq)` 幂等落库与回放。
 
-| 事件 | 典型触发时机 |
-| ---- | ------------ |
-| `RolesAssigned` | `setPlayerRoles` |
-| `HoleCardsDealt` | `dealCards` |
-| `HandStarted` | `start` / `startPreflopWithJoiningBigBlinds` |
+| 事件                     | 典型触发时机                                                                       |
+| ------------------------ | ---------------------------------------------------------------------------------- |
+| `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` | 独赢弃牌或摊牌/跑马结束 |
+| `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` 完成。
 
@@ -200,12 +200,12 @@ async function drainAndConsumePendingFlow(
 
 ## `TableCommand`（`dispatchCommand`）
 
-| `type` | 说明 |
-| ------ | ---- |
-| `Fold` / `Check` / `Call` / `Bet` / `Raise` / `AllIn` | 自愿行动；`Bet`/`Raise` 带 `amount` / `additionalAmount` |
-| `FoldDueToTimeout` / `CheckDueToTimeout` | 计时到期；须当前行动方 |
-| `FoldDueToLeave` | 当前行动方离场弃牌；可先 `canFoldDueToLeave(userId)` |
-| `PostBigBlind` | 翻前补入座大盲；可选 `allowWhenCurrentActor`（服务端可信队列） |
+| `type`                                                | 说明                                                           |
+| ----------------------------------------------------- | -------------------------------------------------------------- |
+| `Fold` / `Check` / `Call` / `Bet` / `Raise` / `AllIn` | 自愿行动；`Bet`/`Raise` 带 `amount` / `additionalAmount`       |
+| `FoldDueToTimeout` / `CheckDueToTimeout`              | 计时到期；须当前行动方                                         |
+| `FoldDueToLeave`                                      | 当前行动方离场弃牌；可先 `canFoldDueToLeave(userId)`           |
+| `PostBigBlind`                                        | 翻前补入座大盲；可选 `allowWhenCurrentActor`（服务端可信队列） |
 
 JSON 解析：`parseTableCommandFromJson` / `parseTableCommandFromUnknown`。
 
@@ -213,21 +213,21 @@ 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` |
+| 方法                                                | 说明                                                       |
+| --------------------------------------------------- | ---------------------------------------------------------- |
+| `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`                  |
 
 ---
 
@@ -260,13 +260,13 @@ Texas.resetEngineContext() // jest.setup 已 beforeEach 调用
 
 ## 更多文档
 
-| 文档 | 内容 |
-| ---- | ---- |
-| [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/) | 事件化架构与路线图 |
+| 文档                                                                                                     | 内容                                 |
+| -------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| [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/) | 事件化架构与路线图                   |
 
 ---
 
@@ -716,6 +716,12 @@ reject modulo bias
 贴盲与 game start 原子化
 
 ## 1.4.29
-修复post bb玩家过牌导致的异常
+
+修复 post bb 玩家过牌导致的异常
+
 ## 1.4.30
-同步README接入文档
+
+同步 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.30",
+  "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 {};