# Proposal: single-react-rag-log-projections

## Problem

阶段 3A 已提供统一 `ToolBoundary` 和 canonical invocation store，但 RAG 与 `query_logs` 仍只有旧工具输出。旧输出包含检索轨迹、上下文打包、基础设施字段、实例信息和未受约束的日志内容，不能直接作为单体 Diagnosis Agent 的 ACI evidence projection。若分别实现状态机或存储，会重新引入重复的生命周期、Run ownership 和错误处理逻辑。

## Proposed change

- 新增 RAG result projector，将旧 `LookupKnowledgeTool` JSON 转换为冻结的 `RagToolResult`。
- 新增 query-log result projector，将现有 Mock `QueryLogsTools` JSON 转换为冻结的 `QueryLogsToolResult`。
- projector 负责精确摘录、文档去重、证据/事件/模式数量上限、整体字符预算、时间线抽样和脱敏。
- projector 由请求感知适配层调用，使 `topic`、`query` 和 `lookback_minutes` 保留在完整 `scope` 中；不扩展 Agent request，不让 raw response 直接进入 Agent。
- 两个适配器均通过阶段 3A `ToolBoundary` 执行，沿用框架 `tool_call_id`、RunContext、canonical store、`PROJECTING/READY/ERROR` 与 `EVIDENCE_FOUND/NO_EVIDENCE/ERROR` 语义。
- 保留旧工具、旧 recorder、Chat/AIOps、Controller 和公开协议不变；本阶段只新增投影/适配层与 focused tests。

## Scope

### In scope

- RAG projector and adapter.
- Query-log projector and adapter for existing Mock source.
- Request-aware projection entry point required to preserve log scope.
- Contract, sanitization, deduplication, truncation, no-evidence and boundary integration tests.

### Out of scope

- Real CLS/MCP log integration.
- MySQL projector (stage 3C).
- Diagnosis Agent cutover, Guards, Chat use-case cutover, SSE changes, or legacy recorder cleanup.
- Changes to the frozen ACI DTO field names.

## Constraints and risks

- Raw payload remains Harness-only canonical data and is never returned to the Agent.
- `NO_EVIDENCE` is scoped to the recorded query and time window; it is not a health claim.
- Log messages may contain credentials, hostnames, pod IDs, SQL literals, or stack traces; projection must redact these before Agent exposure.
- A projector must not silently truncate raw data. It may bound Agent-facing collections and excerpts while setting `truncated=true`.
- The existing generic `ToolResultProjector` API has no request argument. The adapter will carry the typed request alongside the projector invocation, keeping the generic boundary reusable and avoiding a raw JSON scope convention.

## Acceptance direction

- Serialized RAG output contains only the frozen fields and bounded exact excerpts.
- Serialized log output contains complete logical scope, `source_kind=MOCK`, bounded patterns/events, distinct match and returned counts, and no infrastructure controls.
- Both projectors produce `NO_EVIDENCE` for successful empty results and `ERROR` for malformed/unsafe input.
- Boundary tests prove framework ID preservation, canonical lifecycle reuse, raw isolation, and safe errors.

## Context sources

- ISS-014 stage 3B requirements.
- `aci-evidence-tool-contracts` and `canonical-tool-invocation-store` specifications.
- Existing `LookupKnowledgeTool`, `QueryLogsTools`, and frozen contract tests.