docs(api): 事件重复投递/幂等语义

[DeliciousBuding]

Summary

• SYNTHESIS A3：为全部 30 个 live Hub WS frame（frame.go / HUB_EVENTS / OpenAPI 1:1）在 api/events.md 补「幂等键 + 重复投递语义」栏：UPSERT by id / idempotent on apply / 水位 / ephemeral。
• 明确 seq_id 仅为 per-connection 投递序，不是业务幂等键；at-least-once + 离线/outbox 重放场景下客户端必须按业务键 apply。
• frame.go / hubEvents.ts 旁注指向该合同；hubEvents.test.ts 钉死文档覆盖全部 live type，并禁止把 hub/web: WS 死协议面 — sync.request 无服务端实现、agent.regenerate/message.edited 无生产者、plan_* 无 Hub 传输 #1362/chore(ws): 删除无生产者死协议面与坏死 useHubWebSocket #1422 死面写回语义表。
• 这是 WS 增量同步 SPEC（docs(plan): WS 增量同步 Subscribe-with-Snapshot 提案 #1412）的文档先修：无幂等声明的 blind replay 不安全。

Coverage (30)

typing, auth.ok, message×7, session×5, device×3, agent×6, team×4, notification.new, friend.request, friend.accepted.

Dead surface not reintroduced: sync.*, auth/auth.fail, agent.regenerate, message.edited, agent.timeout wire, run.agent.plan_*.

Test plan

• Node 一致性检查：go frame 常量 ↔ HUB_EVENTS ↔ events.md 语义表（30/30）
• go test ./internal/ws in hub-server
• openapi yaml load ok
• CI shared vitest hubEvents.test.ts（worktree vitest 依赖解析受限，由 CI 兜底）

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

Warning

Review limit reached

@DeliciousBuding, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 42 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e52a3d4a-10fb-447d-8775-d193414eb987

📥 Commits

Reviewing files that changed from the base of the PR and between 7160400 and b8fa0ec.

📒 Files selected for processing (4)

• api/events.md
• app/shared/src/hubEvents.test.ts
• app/shared/src/hubEvents.ts
• hub-server/internal/ws/frame.go

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/event-idempotency

---

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.}