Use Stable Negative IDs for Anonymous Card Slots and Materialize Unresolved Identities

[llsccm]

Summary by CodeRabbit

• 新功能

  • 匿名实体改用稳定的负数标识，支持后续揭示时平滑绑定真实身份。
  • 优化牌堆、公共区域与手牌之间的匿名牌物化、回补及身份追踪。
  • 新增公共区域端点牌获取与批量物化能力。
  • 增强身份守恒检查、异常告警及状态索引维护。

• 错误修复

  • 改善洗牌、明牌展示、跨区域移动及重复同步时的匿名占位处理。
  • 修复公共区域牌堆顺序、候选传播和缺失身份回补场景。

• 测试

  • 新增并扩展匿名身份、牌堆物化、公共端点及守恒校验测试。

• 文档

  • 同步更新相关协议、记牌器、测试及开发说明中的匿名实体规则。

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8c5fd34c-bd21-4cc4-85c8-e16b49b9d45f

📥 Commits

Reviewing files that changed from the base of the PR and between bd859b6 and 797271e.

📒 Files selected for processing (2)

• src/tracker/Room.ts
• tests/tracker/publicEndpointCards.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/tracker/Room.ts

---

📝 Walkthrough

Walkthrough

本次变更将匿名牌从 id=0 占位改为稳定负数身份，新增身份集合、端点物化、索引注册和守恒校验，并调整移动、展示、候选传播及相关测试和文档。

Changes

匿名身份与牌堆模型

Layer / File(s)	Summary
身份集合与物化核心 src/tracker/Card.ts, src/tracker/Room.ts, src/tracker/CardCounter.ts	匿名卡使用稳定负数 ID；Room 管理 deckIdentities、unlocatedIdentities，并支持公共端点物化；CardCounter 为未定位身份建立 UNKNOWN 索引。
牌堆收敛与守恒校验 src/tracker/Room.ts	洗牌流程统一使用匿名判定，暂停身份通过匿名替身保留，并新增开发期身份、索引和公共槽守恒检查。

移动与展示流程

Layer / File(s)	Summary
移动来源解析与占位回补 src/tracker/roomMovement.ts, src/tracker/roomMovement/*	已知移动按公共端点和匿名槽恢复实体，公共区回补改用匿名占位替换，来源取牌统一使用 isAnonymous。
公共区展示物化 src/tracker/runtime/trackerController.ts	展示和揭示流程将目标区域与位置传入已知牌解析，按公共端点物化身份，并调整重复同步与无法物化身份处理。

测试与文档

Layer / File(s)	Summary
测试夹具与遍历统计基础 src/tracker/traversalStats.ts, tests/tracker/helpers/room.ts, tests/tracker/*	测试夹具支持匿名牌堆身份物化和缺失卡物化取卡，遍历统计抽出统一的统计创建与累加辅助逻辑。
匿名身份、牌堆与展示测试 tests/tracker/*	新增并更新匿名 ID、牌堆物化、UNKNOWN 索引、展示幂等、端点位置、候选传播和守恒告警测试。
协议与工作文档 docs/agents/*, docs/protocols/hand-exchange.md	文档同步记录稳定负数匿名实体、匿名牌堆账本和阶段验证结论。

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• llsccm/tracker#44：涉及同一套匿名牌堆槽、身份集合和端点物化流程。
• llsccm/tracker#2：涉及同一控制器中的展示、揭示和已知牌解析链路。
• llsccm/tracker#4：涉及 Room.shufflePile 的牌堆数量与占位处理。

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title Check	✅ Passed	Title check skipped as CodeRabbit has written the PR title.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/anonymous-slot-identity-decoupling-plan.md`:
- Around line 104-106: 将文档中匿名占位（anonymous placeholder）的 ID 约束从 id<=0 统一改为
id<0，确保与 Room.assertConservation() 及匿名身份测试的严格负数约定一致；仅修改该处相关表述。
- Around line 111-116: Update both fenced code blocks in the document to use the
text language identifier (` ```text `), including the block containing the
identity-state mapping and the additional block referenced by the review.
- Around line 122-126: 将 I1 的身份守恒公式基准改为 `deckIdentities`：把“全牌集”明确替换为
`deckIdentities`，以覆盖 `Room.materialize()` 运行时加入的合法正 ID；保持其余身份唯一性约束不变。

In `@docs/anonymous-slot-stage-1-comparison.md`:
- Around line 151-158: 更新文档第 3
节的回放结论，移除或改写“旧冲突路径为零触发”，明确旧路径已删除且未被运行时采集，不能作为观测证据；仅将仍在运行的路径标记为实际回放观测为 0，并同步调整 G1
的 NO-GO / 收缩结论以区分结构性结果与实证数据。

In `@src/tracker/Room.ts`:
- Around line 498-503: 更新 getPublicEndpointCards，先将 position 统一归一化为
POSITION_BOTTOM 等数值常量，或直接兼容字符串“bottom”，确保未归一化的 bottom 走牌底分支而不是默认牌顶分支；同时检查
resolveKnownMoveCards 和 materializeAtPublicEndpoint 的传入值，保持位置语义一致。

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e83c95ea-32dc-42a1-9195-fcf3cbdfbc13

📥 Commits

Reviewing files that changed from the base of the PR and between 450705e and bd859b6.

📒 Files selected for processing (27)

• docs/agents/card_tracker.md
• docs/agents/serena.md
• docs/agents/testing.md
• docs/anonymous-slot-identity-decoupling-plan.md
• docs/anonymous-slot-stage-0-conflict-baseline.md
• docs/anonymous-slot-stage-1-comparison.md
• docs/protocols/hand-exchange.md
• src/tracker/Card.ts
• src/tracker/CardCounter.ts
• src/tracker/Room.ts
• src/tracker/roomMovement.ts
• src/tracker/roomMovement/candidates.ts
• src/tracker/roomMovement/hiddenMarks.ts
• src/tracker/roomMovement/sources.ts
• src/tracker/runtime/trackerController.ts
• src/tracker/traversalStats.ts
• tests/tracker/anonymousIdentity.test.ts
• tests/tracker/anonymousPileSpike.test.ts
• tests/tracker/cardCounter.test.ts
• tests/tracker/handCountObservation.test.ts
• tests/tracker/handExchange.test.ts
• tests/tracker/helpers/room.ts
• tests/tracker/moveCardRoutes.test.ts
• tests/tracker/pileDisplayOrder.test.ts
• tests/tracker/publicCandidates.test.ts
• tests/tracker/trackerController.test.ts
• tests/tracker/traversalBaseline.test.ts