74 lines
3.8 KiB
Markdown
74 lines
3.8 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.
|
|
|
|
## ADDED 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.
|
|
|
|
#### Scenario: RAG evidence is projected
|
|
|
|
- WHEN the legacy response contains usable evidence blocks
|
|
- THEN the result contains the original query, framework `tool_call_id`, deduplicated evidence with exact bounded excerpts, a returned count, and an explicit truncation flag
|
|
|
|
#### Scenario: RAG result has no usable excerpt
|
|
|
|
- WHEN the legacy response has no usable evidence block
|
|
- THEN the boundary returns `READY` with `evidence_status=NO_EVIDENCE`, the original query and an empty evidence list
|
|
|
|
#### Scenario: RAG duplicate documents
|
|
|
|
- WHEN multiple blocks identify the same source/document
|
|
- THEN only the first document is returned and the result remains deterministic
|
|
|
|
### 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: Mock logs are projected
|
|
|
|
- WHEN the legacy Mock response contains log entries
|
|
- THEN the result includes the logical topic/query/time window, sanitized pattern aggregates, sanitized timeline events, distinct match and returned counts, and `source_kind=MOCK`
|
|
|
|
#### Scenario: Empty Mock result
|
|
|
|
- WHEN the legacy Mock response is successful with an empty log array
|
|
- THEN the boundary returns `READY` with `evidence_status=NO_EVIDENCE` and preserves the full query scope
|
|
|
|
#### Scenario: Legacy log error
|
|
|
|
- WHEN the legacy response indicates failure or is malformed
|
|
- THEN the boundary returns `ERROR` with a bounded projection error and no Agent result
|
|
|
|
### 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: Sensitive fields are present
|
|
|
|
- WHEN a log entry includes instance, metrics, a secret assignment, a pod identifier or a SQL literal
|
|
- THEN none of those raw values are present in the projected Agent result
|
|
|
|
#### Scenario: Projection exceeds collection budget
|
|
|
|
- WHEN evidence, patterns, events or excerpts exceed configured bounds
|
|
- THEN the result is valid JSON, contains only bounded collections, and sets `truncated=true`
|
|
|
|
### 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: Framework ID and Run are valid
|
|
|
|
- WHEN an adapter executes a valid request
|
|
- THEN the canonical record and bounded result use the exact framework ID and the current Run ID
|
|
|
|
#### Scenario: Boundary rejects the request
|
|
|
|
- WHEN Run ownership, authorization, read-only, duplicate, budget or size preflight fails
|
|
- THEN the adapter returns the boundary's safe error without invoking the legacy tool or projector
|