feat(harness): add rag and log projections

2026-07-21 20:12:18 +08:00
parent 0dbdd7d8d3
commit 3e602781d6
20 changed files with 1140 additions and 0 deletions
@@ -0,0 +1,25 @@
+# Acceptance: single-react-rag-log-projections
+
+## Commit preflight
+
+- OpenSpec strict validation: passed.
+- Scope: RAG and Mock query-log projectors/adapters through the existing ToolBoundary.
+- Explicit non-goals: real CLS/MCP, MySQL, Diagnosis Agent cutover, public Chat/AIOps/SSE changes, legacy recorder cleanup.
+- Main residual risk: legacy log payloads contain sensitive values; projector tests must prove redaction before Agent serialization.
+
+## Apply acceptance
+
+- Implemented and verified.
+- Static verification and focused/regression Maven tests are recorded in `evidence.md`.
+- No browser/manual verification applies; this stage adds no UI or public protocol change.
+- Residual risks: live Redis/CLS integration and Agent cutover remain later stages.
+
+## Archive acceptance
+
+- `.archive-ready` marker is created after all tasks and checks pass.
+- OpenSpec is ready to move to the dated archive directory.
+- Archive completed at `openspec/changes/archive/2026-07-21-single-react-rag-log-projections`.
+
+## Remaining work
+
+- Real Redis/CLS integration, MySQL projection, Diagnosis Agent cutover and final E2E remain later stages.
@@ -0,0 +1,24 @@
+# Brief: single-react-rag-log-projections
+
+## Background
+
+阶段 3A 已经统一 ToolBoundary 和 canonical invocation store。下一阶段需要把现有 RAG 与 Mock 日志工具接入该边界，并把旧工具输出投影为冻结的 Agent-facing ACI 结果。
+
+## Goal
+
+- 提供 bounded RAG evidence projection。
+- 提供带完整 logical scope 和 Mock provenance 的 query-log projection。
+- 复用阶段 3A 生命周期、Run ownership、tool_call_id、预算、错误和 canonical record。
+
+## Non-goals
+
+- 不接入真实 CLS/MCP。
+- 不实现 MySQL projection。
+- 不切换 Diagnosis Agent、Chat/AIOps、SSE 或旧 recorder。
+
+## Classification
+
+- Scale: complex
+- Interface impact: L2 internal Harness adapter/projector
+- Issue: ISS-014 stage 3B
+- Change slug: `single-react-rag-log-projections`
@@ -0,0 +1,72 @@
+# Decisions: single-react-rag-log-projections
+
+## Discover status
+
+- Checkpoint: Discover
+- Capability source: `sm-flow` with `grill-with-docs` codebase evidence; no external service integration required.
+- Scale: complex, because two tool adapters share a lifecycle boundary and define bounded Agent-facing output semantics.
+
+## Evidence-driven findings
+
+1. `ToolBoundary` currently accepts `project(String rawResponse)` and already owns Run/ID/authorization/read-only/JSON/budget/lifecycle enforcement.
+2. `LookupKnowledgeTool` emits `evidenceBlocks`, `contextPack`, `retrievalTrace`, `rerankTrace`, session domains, and message; these are internal retrieval/audit fields and must not be projected.
+3. `QueryLogsTools` emits region, physical log topic, result limit, instance and metrics; the frozen contract requires logical topic/query/lookback scope and `source_kind=MOCK` instead.
+4. Existing ACI records already define the required snake_case fields and immutable collections.
+5. The request scope must be passed to the log projector through a typed adapter method rather than inferred from raw output.
+
+## User-confirmed direction
+
+- Use the framework-provided `tool_call_id` only.
+- Keep lifecycle status and evidence status separate.
+- Implement the stage in phases and complete sm-flow archive plus Git commit before the next stage.
+- Adopt the request-aware projector adapter for log scope preservation.
+
+## Question pool
+
+| Dimension | Question | Mode | Conclusion | Status |
+|---|---|---|---|---|
+| Terminology | Are RAG traces and context packs Agent evidence? | evidence-driven | No. They are internal retrieval/audit details and are excluded from projection. | resolved |
+| Boundary | How is log scope preserved when the generic projector has no request? | evidence-driven | Typed adapter carries `QueryLogsRequest` into a request-aware projector method. | resolved |
+| Provenance | Which log source is implemented now? | evidence-driven | Existing Mock source only; result always records `source_kind=MOCK`. | resolved |
+| Negative result | What does an empty query mean? | evidence-driven | `NO_EVIDENCE` for the recorded scope, with no health/problem inference. | resolved |
+| Compatibility | Should legacy tools and public paths be changed now? | evidence-driven | No. Add adapters/projectors only; cutover is later. | resolved |
+
+## Risks
+
+- Existing mock messages contain hostnames, pod IDs, SQL literals, and stack-like text; sanitization must happen before projection.
+- Collection limits and excerpt limits can make the Agent result incomplete; `truncated` must be explicit.
+- The generic boundary API should remain reusable for stage 3C, so request-aware behavior belongs in an adapter or specialized projector interface.
+
+## Discover checkpoint
+
+- Proposal created: `openspec/changes/single-react-rag-log-projections/proposal.md`
+- Context and issue evidence recorded.
+- No unresolved user-interview question remains for this bounded stage; implementation direction was explicitly accepted in the conversation.
+
+## Commit audit
+
+- Capability source: `sm-flow` and local OpenSpec CLI.
+- OpenSpec strict validation: passed for `single-react-rag-log-projections`.
+- Cross-artifact alignment:
+  - brief goals/non-goals -> proposal scope: aligned.
+  - proposal boundaries and request-aware projector decision -> design: aligned.
+  - design projection bounds, redaction, scope and adapter ownership -> spec requirements: aligned.
+  - spec scenarios -> tasks for limits, RAG, logs, boundary integration and verification: aligned.
+- Interface impact: L2 internal Harness adapter/projector only; no public protocol or legacy runtime cutover.
+- Preflight risks accepted: legacy payload drift fails closed; sensitive log fields are redacted; total projection budget is explicit.
+
+## Commit gate
+
+- [x] proposal, design, specs and tasks exist.
+- [x] strict OpenSpec validation passes.
+- [x] all evidence-driven questions are resolved.
+- [x] no unresolved interface decision remains.
+- [x] `.committed` marker created for Apply.
+
+## Archive result
+
+- Apply tasks complete.
+- `.archive-ready` marker created.
+- OpenSpec archived at `openspec/changes/archive/2026-07-21-single-react-rag-log-projections`.
+- Main capability specification added at `openspec/specs/rag-log-projections/spec.md`.
+- Next stage remains 3C MySQL projection; no Agent cutover is implied by this archive.
@@ -0,0 +1,25 @@
+# Evidence: single-react-rag-log-projections
+
+## Static verification
+
+- `git diff --check`: passed.
+- Existing legacy files were checked and have no diff: `LookupKnowledgeTool`, `QueryLogsTools`, `ChatService`, `AiOpsService`, and `ToolInvocationRecorder`.
+- OpenSpec strict validation: passed for `single-react-rag-log-projections`.
+
+## Script/build verification
+
+- `mvn -q -DskipTests compile`: passed.
+- Focused projection tests: passed (`RagResultProjectorTest`, `QueryLogsResultProjectorTest`).
+- Adapter tests: passed (`ToolAdapterTest`).
+- Stage regression suite: passed (`CanonicalInvocationStoreTest`, `ToolBoundaryTest`, ACI/Core/retry/key/config/ChatController tests plus the new projection tests).
+
+## Coverage
+
+- RAG: bounded exact excerpts, duplicate document IDs, internal field exclusion, `NO_EVIDENCE`, truncation and framework ID.
+- Logs: logical scope, Mock provenance, pattern aggregation, timeline sampling, sensitive value redaction, empty result and bounded output.
+- Boundary: adapters use the existing canonical lifecycle and do not return raw payloads.
+
+## Not verified in this stage
+
+- Real Redis connectivity and live CLS/MCP integration.
+- Diagnosis Agent/application cutover and end-to-end Maven runtime flow.