feat(harness): freeze aci tool contracts

2026-07-21 18:01:18 +08:00
parent 58c39107c5
commit 4274f3350b
32 changed files with 977 additions and 1 deletions
@@ -0,0 +1,70 @@
+## ADDED Requirements
+
+### Requirement: Evidence result semantics SHALL be distinct from invocation lifecycle
+The system SHALL expose `EVIDENCE_FOUND`, `NO_EVIDENCE`, and `ERROR` as Agent-facing evidence result semantics while retaining `PROJECTING`, `READY`, and `ERROR` only for canonical invocation lifecycle. `NO_EVIDENCE` SHALL mean that the executed query found no evidence within its recorded scope and SHALL NOT mean tool failure or system health.
+
+#### Scenario: Successful empty query result
+- **WHEN** an evidence Tool completes successfully with no matching evidence in its recorded scope
+- **THEN** its Agent-facing result uses `evidence_status=NO_EVIDENCE` and the invocation lifecycle may independently reach `status=READY`
+
+#### Scenario: Tool execution fails
+- **WHEN** schema, authorization, execution, or projection fails
+- **THEN** the Agent-facing result uses `evidence_status=ERROR` and SHALL NOT report `NO_EVIDENCE`
+
+### Requirement: Referencable Tool results SHALL use the framework Tool Call ID
+Each `EVIDENCE_FOUND` or `NO_EVIDENCE` result SHALL contain the non-blank `tool_call_id` supplied by the framework Tool Call request. Agent inputs SHALL NOT contain `tool_call_id`, and contract code SHALL NOT generate, replace, or derive a second call ID.
+
+#### Scenario: Framework requests a Tool call
+- **WHEN** Spring AI Alibaba exposes an `AssistantMessage.ToolCall.id` through `ToolCallRequest.getToolCallId()`
+- **THEN** the bounded Agent result carries exactly that ID as `tool_call_id`
+
+#### Scenario: Framework ID is invalid
+- **WHEN** the Tool request has a missing or invalid framework Tool Call ID
+- **THEN** the call returns an `ERROR` result without inventing a referencable ID
+
+### Requirement: RAG Tool contract SHALL expose only bounded document evidence
+The RAG Request SHALL contain only `query`. The RAG Result SHALL contain `evidence_status`, `tool_call_id`, `query`, bounded `evidence`, `returned_count`, and `truncated`; each evidence item SHALL contain only `document_id`, `source`, `title`, `breadcrumb`, and an exact `excerpt`.
+
+#### Scenario: RAG evidence is serialized
+- **WHEN** a RAG result contains a matching document excerpt
+- **THEN** its JSON matches the frozen snake_case fields and excludes ContextPack, RetrievalTrace, RerankTrace, raw scores, fallback attempts, metadata, and full document bodies
+
+#### Scenario: RAG query has no evidence
+- **WHEN** RAG executes successfully without a usable document excerpt
+- **THEN** it returns `NO_EVIDENCE`, preserves the original query and framework Tool Call ID, and returns an empty evidence list
+
+### Requirement: Log Tool contract SHALL use logical scope and retain Mock provenance
+The log Request SHALL contain logical `topic`, `query`, and optional `lookback_minutes` only. The log Result SHALL contain `evidence_status`, `tool_call_id`, `source_kind`, complete query `scope`, `match_count`, `returned_count`, bounded `patterns`, bounded timeline `events`, and `truncated`. The initial logical topics SHALL be `APPLICATION`, `DATABASE_SLOW_QUERY`, and `SYSTEM_EVENTS`, and the initial source kind SHALL be `MOCK`.
+
+#### Scenario: Mock log evidence is serialized
+- **WHEN** the existing Mock source returns matching application events
+- **THEN** the Agent result records `source_kind=MOCK`, the logical query scope, aggregate patterns, bounded timeline events, and distinct match and returned counts
+
+#### Scenario: Agent creates a log request
+- **WHEN** the Agent requests log evidence
+- **THEN** it selects a logical topic and lookback window without supplying region, physical TopicId, credentials, or result limit and without calling a Topic discovery Tool first
+
+### Requirement: MySQL Tool contract SHALL expose a logical read-only query interface
+The MySQL Request SHALL contain only logical `data_source`, parameterized `sql`, and `params`. The MySQL Result SHALL contain `evidence_status`, `tool_call_id`, `columns`, bounded structured `rows`, `returned_count`, and `truncated`; it SHALL NOT expose connection details, credentials, internal stack traces, or resource-limit controls.
+
+#### Scenario: MySQL evidence is serialized
+- **WHEN** a future read-only adapter returns authorized rows
+- **THEN** the Agent result preserves column order, structured row values, the framework Tool Call ID, returned count, and truncation state using the frozen JSON fields
+
+#### Scenario: Agent creates a MySQL request
+- **WHEN** the Agent requests business database evidence
+- **THEN** it supplies a logical data source, SQL placeholders, and parameter values without supplying JDBC connection information or security policy
+
+### Requirement: Tool descriptions SHALL be concise and implementation-neutral
+The system SHALL define stable snake_case names and concise descriptions for `lookup_knowledge`, `query_logs`, and `query_mysql`. Each description SHALL state when to call the Tool, its minimal input, and what it cannot query, and SHALL NOT describe retrieval internals, infrastructure coordinates, credentials, audit storage, retries, result limits, or ranking implementation.
+
+#### Scenario: Agent receives Tool definitions
+- **WHEN** a future Agent adapter registers the frozen Tool definitions
+- **THEN** the definitions describe available actions and boundaries without exposing Milvus, L0/L1, rerank, CLS region/TopicId, Redis, JDBC credentials, topK, limit, or Trace internals
+
+### Requirement: Contract freeze SHALL NOT cut over the current runtime
+This change SHALL add contract types, descriptions, and tests without changing the current `LookupKnowledgeTool`, `QueryLogsTools`, ChatService, AiOpsService, Controller, Tool registration, or Agent-visible runtime results.
+
+#### Scenario: Stage 1 tests pass
+- **WHEN** all ACI contract tests pass
+- **THEN** the current public Chat and AIOps paths still execute the old Tool implementations until their later projector and cutover changes