SuperBizAgent-java/openspec/changes/archive/2026-07-21-single-react-rag-log-projections/specs/rag-log-projections/spec.md

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