Files

T

zhuyongxin ac1f831903 feat(rag): chunk evidence identity, dedup, and search port

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.

2026-07-27 18:26:15 +08:00

3.3 KiB

Raw Blame History

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

3.3 KiB Raw Blame History