zhuyongxin
ac1f831903
Preserve same-document multi-chunk evidence with evidenceKey identity, per-document caps, retrieve-k/return-n split, and a dense KnowledgeSearchPort. Archives Delivery 1 OpenSpec change as the foundation for hybrid retrieval.
50 lines
3.3 KiB
Markdown
50 lines
3.3 KiB
Markdown
# rag-log-projections Specification
|
|
|
|
## Purpose
|
|
|
|
Define bounded RAG and Mock query-log projections that execute through the stage 3A ToolBoundary and expose only the frozen ACI contracts to the Agent.
|
|
## Requirements
|
|
### Requirement: RAG projection SHALL expose bounded document evidence only
|
|
|
|
The RAG adapter SHALL accept the logical `query` request, execute the existing knowledge tool through ToolBoundary, and project only `RagToolResult` fields. Context packs, retrieval traces, rerank traces, scores, hit reasons, domains, messages and full document bodies SHALL NOT appear in the Agent result. Projected evidence identity SHALL be chunk-scoped when chunk identity is available, allowing multiple excerpts from one logical source document.
|
|
|
|
#### Scenario: Project only bounded RAG evidence
|
|
|
|
- **WHEN** the adapter receives a logical query and the knowledge backend returns a result
|
|
- **THEN** it invokes through ToolBoundary and exposes only the bounded `RagToolResult` evidence fields, excluding retrieval internals and full document bodies
|
|
|
|
#### Scenario: Multiple chunks from one source may project
|
|
|
|
- **WHEN** the backend returns multiple evidence blocks with the same source and different chunk-scoped identities
|
|
- **AND** projection budgets allow them
|
|
- **THEN** the projected evidence list SHALL include more than one item for that source
|
|
- **AND** each item SHALL have a distinct `document_id`
|
|
|
|
### Requirement: Query-log projection SHALL preserve logical scope and Mock provenance
|
|
|
|
The query-log adapter SHALL accept only logical topic, query and optional lookback minutes, execute the existing Mock source through ToolBoundary, and project `source_kind=MOCK`, complete scope, match count, returned count, bounded patterns, bounded timeline events and truncation.
|
|
|
|
#### Scenario: Return a bounded Mock query-log projection
|
|
|
|
- **WHEN** the adapter receives a logical topic, query, and optional lookback
|
|
- **THEN** it invokes the Mock source through ToolBoundary and returns `source_kind=MOCK`, the complete logical scope, bounded matches and timeline events, counts, and truncation
|
|
|
|
### Requirement: Projection SHALL redact and bound sensitive log content
|
|
|
|
The log projector SHALL exclude instance and metrics fields and redact credentials, token-like values, host/pod identifiers, PIDs, IP addresses, SQL literals and stack-like suffixes from Agent-facing messages. It SHALL enforce per-item, collection and total UTF-8 bounds and set `truncated=true` when any bound removes data.
|
|
|
|
#### Scenario: Redact sensitive log fields and mark truncation
|
|
|
|
- **WHEN** a log result contains credentials, identifiers, SQL literals, stack suffixes, or content beyond configured UTF-8 bounds
|
|
- **THEN** those values are omitted or redacted and `truncated=true` indicates removed content
|
|
|
|
### Requirement: Adapters SHALL reuse canonical boundary ownership
|
|
|
|
Both adapters SHALL pass the framework `tool_call_id` and RunContext to the existing ToolBoundary and SHALL NOT create a second ID, write a parallel store, return raw responses, or modify legacy audit paths.
|
|
|
|
#### Scenario: Preserve canonical identity for both adapters
|
|
|
|
- **WHEN** either the RAG or query-log adapter executes
|
|
- **THEN** it passes the exact framework `tool_call_id` and RunContext through ToolBoundary without creating a second identifier, parallel store, raw response path, or legacy audit side effect
|
|
|