feat: 增加 Kafka 会话顺序单步诊断

docs/reference/kafka-source-direct-debug.md

@@ -8,6 +8,19 @@
   - group prefix 必须标识独立 debug group，不复用产品 consumer group；
   - 命令只读取 Kafka，不发布事件，不启动 Cloud API，不访问数据库，也不依赖 projector。
 
+- `hwlab-cli kafka inspect order` 用于定位同一 session 在纯 Kafka 刷新链路中的首个顺序分歧：
+  - 已知 session 时使用 `--session-id <sessionId>`；
+  - 只知道用户输入时使用 `--contains-text <bounded-user-text>` 从 HWLAB retention 解析唯一 session；
+  - 文本发现只披露长度和 SHA-256，不回显用户正文；
+  - 命令分别扫描 `agentrun.event.v1` 与 `hwlab.event.v1` 到启动时捕获的 topic 上界；
+  - `hwlabSessionId` 及其 snake case 形式属于两个 topic 共用的正式 session identity 候选；
+  - HWLAB retained event 复用生产 refresh handoff、SSE frame 解码、queue/reducer 和 timeline row model；
+  - 输出逐层 transport、stable identity、`sourceSeq`、message index 和 DOM row index；
+  - `firstDivergence` 只报告首个改变顺序的层，不过滤、重排或补写任何事件；
+  - `--row-limit` 只限制返回的有界尾部明细，不改变全量计数和判定；
+  - 任一 topic 未到捕获上界时返回 `partial/source_scan_incomplete`，禁止根据部分扫描下结论；
+  - 命令只读取既有 Kafka retention，不发布事件，也不启动新的 AgentRun。
+
 - Trace 渲染与 Web 共享最后一个展示分叉之前的生产管线：
   - JSON frame 使用 `decodeWorkbenchRealtimeEventFrame` 解码；
   - 事件使用 `reduceWorkbenchRealtimeEvent` 与 `planWorkbenchRealtimeApply` 分类；