T01 公开头契约注释与回调判据骨架 #86

Parent

#85 — [Spec] 播放器状态与公开 API 契约实现计划。本批票以 [Tnn] 前缀编号，阻塞边用 GitHub 原生依赖关系。

What to build

SDK 接入方只靠公开头就能读到回调契约：线程上下文、重入禁令、异常与所有权、停机期；同时测试侧有一个可复用的回调序列记录能力，让后续票能把「顺序 / 计数 / 无相邻重复」写成可红可绿的判据。

• 按规格 §10.2 的建议文本给 PlayerCallbacks 加注释（五条：单一串行线程同步发出、marshal 归调用方、回调内禁发控制命令 / 禁析构 / 禁抛异常、callbacks 须活过 Player 析构、停机期不发送也不保证）。
• 扩展既有回调记录器，使其能按发生顺序记录六个回调与参数，且不影响既有断言。
• 不改任何生产链行为、不改任何公开签名；注释是契约的唯一新增内容。

Acceptance criteria

• 公开头的注释覆盖线程 / 重入 / 异常 / 所有权 / 停机期五条，措辞与规格 §10.2 一致
• 回调序列记录器可在既有三个测试分组中复用，既有断言数值一字不动
• 编译通过，既有分组全绿

Blocked by

None (can start immediately). 原生依赖见 issue 的 blocked_by（0 个阻塞）。

必须遵守（来自 spec、ADR 0002/0003/0004 与 doc/bad-input-spec.md）：

• 七个控制入口保持 void；不新增错误码、不改 onError 签名、不新增状态机、不扩状态集合（对外仍 Playing/Paused/Stopped 三态）。
• 判据不新造数值：沿用 max(1%,150ms)、r × good、5pp、零容差差分、getter 与回调 ≤50ms、状态序列无相邻重复、每曲一次 duration。
• 坏输入 55 例 / 396 断言与覆盖度矩阵 15 行一字不动；14 个 sdk_* ctest 目标、TIMEOUT、-j4、快集 / 全量集划分全部不动。
• 新增用例若写文件必须带 pid（-j4 撞名假红的教训）；线程契约用 promise/future 或轮询验证，不裸 sleep。
• 事实基线见 #76 的 research/public-api-contract-facts 分支；术语见 GLOSSARY.md。