# R2.3 隔离 Kafka 重放分层诊断任务报告

## 上下文

- 主问题：
  - [HWLAB #2474](https://github.com/pikasTech/HWLAB/issues/2474)
  - [主问题调查结论](https://github.com/pikasTech/HWLAB/issues/2474#issuecomment-4935408473)
- 隔离重放专项：
  - [HWLAB #2476](https://github.com/pikasTech/HWLAB/issues/2476)
  - [隔离重放根因](https://github.com/pikasTech/HWLAB/issues/2476#issuecomment-4935398125)

## 完成结果

- AgentRun 到 HWLAB 的 debug producer 增加批次关联合同：
  - 每批生成或接受一个 `replayId`；
  - 每个 `hwlab.event.debug.v1` envelope 保留 `replayId`、批次序号和原始 AgentRun lineage；
  - 正常 Kafka 调试默认读取 canonical `agentrun.event.v1`；
  - `agentrun.event.debug.v1` 仅由调用方显式选择，用于 stdio partial reconstruction；
  - Kafka 读取只做映射预检，发布必须显式指定 `--publish`。
- debug producer 形成确定的输出 barrier：
  - 只向 YAML 指定的隔离 debug topic 发布；
  - 所有批次记录固定写入 debug topic 的 partition 0；
  - 由 Kafka publish metadata 返回 `firstOffset`、`lastOffset` 和 `count`；
  - 发布后无法形成唯一 offset range 时，以 `debug_publish_barrier_missing` 失败关闭。
- correlated v2 consumer 直接定位该 barrier：
  - 新 group 完成 assignment 后执行 `seek(firstOffset)`，不从增长中的 debug topic 起点盲扫；
  - 观测 `lastOffset` 后立即形成完成/停止边界；
  - 缺首尾 offset、缺中间 offset、重复 offset、parse/filter/delivery 少于整批 cardinality 均不能得到 `terminal_complete`；
  - 未携带 v2 参数时保留明确的 `trace-only-v1` 诊断；出现任一 v2 参数时必须同时具备安全 `replayId` 和完整 offset range，显式 producer/source 失败证据不得降级成功。
- debug SSE 在 JSON parse 和 trace/replay filter 前采集 broker 事实：
  - 报告 `scanned`、`barrierScanned`、`parsed`、`traceMatched`、`replayMatched`、`matched` 和 `delivered`；
  - 分别保留 requested、scanned、matched 和 delivered offset range；
  - completion 保留第一条匹配事件的脱敏 source lineage；
  - 服务端明确声明 client counts unavailable；`clientReceived`、`decoded` 和 `applied` 保持 `null`，不伪造浏览器成功计数。
- 新增分层结果合同：
  - producer/source：`producer_not_invoked`、`source_trace_missing`；
  - Kafka/server：`topic_no_append_for_replay`、`record_parse_rejected`、`records_scanned_but_filter_mismatch`、`sse_write_failed`；
  - client：`transport_failed`、`decoder_rejected`、`reducer_rejected`；
  - terminal：`terminal_missing`、`terminal_complete`。
- 输入合同失败关闭：
  - 不完整或逆序 offset range 返回 `workbench_kafka_debug_offset_range_invalid`；
  - 非 `rpl_` 安全标识返回 `workbench_kafka_debug_replay_id_invalid`；
  - product topic 和 product group 继续禁止作为隔离 debug 资源。

## 验证

- 定向命令：

```bash
bun test \
  internal/cloud/workbench-kafka-debug-replay-contract.test.ts \
  internal/cloud/workbench-kafka-sse-debug.test.ts \
  internal/cloud/kafka-event-bridge.test.ts \
  tools/hwlab-cli/kafka-regenerate.test.ts
```

- 结果：
  - `50 pass`；
  - `0 fail`。
- 已覆盖四类 MDTODO 验收结果：
  - empty：`producer_not_invoked`；
  - matched-no-terminal：`terminal_missing`；
  - reducer-rejected：`reducer_rejected`；
  - terminal-complete：`terminal_complete`。
- 产品路径回归：
  - `hwlab` 与 `stdio` diagnostic stream 既有测试通过；
  - live Kafka direct publish/fanout 测试通过；
  - 未启用 projector、read model、snapshot、sync、recovery replay 或 polling。

## 边界与后续集成

- 本子任务未部署或修改 NC01/v03 运行面。
- 集成分支已让 UI 支持透传 `replayId`/`outputBarrier`，并用同一 EventSource 的本地 `received/decoded/applied` 对服务端结果二次复判；四层计数不严格相等时分别返回 transport、decoder 或 reducer typed failure。
- debug topic、debug group 和结果合同仍只属于隔离调试，不接入产品实时事实源。
- 真实 Kafka `seek` 行为与浏览器分层计数仍须由 R2.4 在 NC01/v03 原入口受控验收。
