SuperBizAgent-java/openspec/changes/archive/2026-07-10-session-run-trace-isolation/specs/mvp-demo-trace-acceptance/spec.md

MODIFIED Requirements

Requirement: Diagnosis trace can be queried by session id

The system SHALL expose a read-only HTTP endpoint GET /api/diagnosis/{sessionId}/trace that returns the persisted diagnosis trace for the requested session id. When runId is omitted, the endpoint SHALL return the latest diagnosis run for compatibility. When runId is provided, the endpoint SHALL return that exact run after validating it belongs to the path sessionId.

Scenario: Existing session latest trace is returned

• WHEN a caller requests trace data for a session id that has at least one diagnosis_run
• THEN the system returns a success response containing the resolved run id, session summary, run summary, ordered agent steps, ordered tool invocations, self-evaluation data, final answer, and feedback for the latest run

Scenario: Existing session exact trace is returned

• WHEN a caller requests trace data with GET /api/diagnosis/{sessionId}/trace?runId=run-xxx
• THEN the system validates that runId belongs to sessionId
• AND it returns a success response containing only the trace data for that run

Scenario: Missing session returns not found

• WHEN a caller requests trace data for a session id that does not exist in chat_session, diagnosis_run, or historical compatibility data
• THEN the system returns a 404 response using the existing session-not-found error contract

Requirement: Trace aggregation is read-only

The system MUST build trace output from existing persisted diagnosis tables and MUST NOT mutate chat sessions, diagnosis runs, agent steps, tool invocations, feedback, or chat session state while serving the trace request.

Scenario: Trace query does not change persisted state

• WHEN a caller requests GET /api/diagnosis/{sessionId}/trace
• THEN the system reads diagnosis_run, agent_step, and tool_invocation records and returns an aggregate without saving any of those records

Scenario: Exact trace query does not change persisted state

• WHEN a caller requests GET /api/diagnosis/{sessionId}/trace?runId=run-xxx
• THEN the system reads the specified run and its trace detail records without saving any of those records