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