## Context

The MVP already persists diagnosis execution data across three tables:

- `diagnosis_session`: query, status, answer, counts, feedback, and `self_evaluation`.
- `agent_step`: ordered agent execution records.
- `tool_invocation`: evidence tool calls and retrieval metadata.

Recent work unified chat session ids and persisted tool invocations, so a single session id can now connect user input, agent steps, evidence tools, verifier evaluation, final answer, and feedback. The missing piece is a read-only aggregation API and a documented demo profile/workflow that a reviewer can run without reading database tables manually.

## Goals / Non-Goals

**Goals:**

- Add a trace API that returns one aggregated view for a diagnosis session.
- Keep the trace API read-only and based on existing persistence tables.
- Add an `mvp-demo` profile that makes the demo intent explicit and keeps mock log/metric tools enabled.
- Add a documented end-to-end acceptance case for start, chat, trace query, and feedback.
- Add focused tests for trace aggregation.

**Non-Goals:**

- Do not clean up committed sensitive configuration in this change.
- Do not add database migrations.
- Do not alter `/api/chat`, `/api/chat_stream`, verifier routing, feedback, or document upload behavior.
- Do not create a fully offline fake LLM runtime.

## Decisions

| Decision | Choice | Alternative Considered | Rationale |
|---|---|---|---|
| Trace API shape | Add `GET /api/diagnosis/{sessionId}/trace` | Extend `/api/chat` response | Trace is an observability concern and should not make chat responses larger or change chat clients. |
| Aggregation ownership | New `DiagnosisTraceService` | Put aggregation in controller | Keeps controller thin and allows focused unit tests with mocked repositories. |
| Response DTO | Dedicated nested DTO | Return raw entities or maps | DTO avoids leaking JPA entity details and gives a stable demo-facing contract. |
| Missing session handling | Throw `SessionNotFoundException` and use existing global 404 handler | Return empty success payload | A missing trace is a real lookup miss and should be visible to callers. |
| `self_evaluation` handling | Return raw JSON string and best-effort parsed JSON | Parse only, or ignore parse failures | Raw value preserves evidence even if JSON shape evolves; parsed value improves frontend/demo readability. |
| Demo profile | Add `application-mvp-demo.yml` overlay | Change default `application.yml` | Overlay avoids disturbing current runtime and keeps demo choices explicit. |

## Interface Impact

- Level: L3 collaboration API.
- Reason: This adds a new HTTP endpoint and response contract intended for frontend/demo/reviewer consumption.
- Compatibility: Additive only. Existing callers do not need to change.
- Documentation: The endpoint is documented in the MVP demo acceptance case.

## Data Structures

The trace response contains:

- `session`: session id, query, status, flow, counts, timing, created/updated time, final answer, raw self-evaluation JSON, parsed self-evaluation object, and feedback.
- `steps`: ordered agent steps with step index, agent name, model input/output, thought, tool flag, duration, token count, and created time.
- `toolInvocations`: ordered tool records with id, step id, tool name, input params, output preview, retrieval metadata, duration, success, error, and created time.
- `summary`: counts derived from the returned collections and session fields.

## Risks / Trade-offs

- [Risk] Trace responses may become large for long sessions. -> Mitigation: the MVP returns persisted previews and structured metadata, not raw full external logs.
- [Risk] `self_evaluation` JSON shape may evolve. -> Mitigation: return both raw and best-effort parsed forms.
- [Risk] Demo profile still depends on real DB/Redis/Milvus/LLM. -> Mitigation: document prerequisites and keep mock logs/metrics enabled for repeatable tool evidence.
- [Risk] New endpoint becomes a de facto frontend contract. -> Mitigation: use a dedicated DTO and document L3 additive API impact.

## Migration Plan

- Deploying this change requires only application restart with the new code.
- No database migration is required.
- Rollback is deleting the new endpoint/profile/docs; persisted data remains unchanged.

## Open Questions

- None for this slice. Security and full offline test profile remain deferred by explicit user decision.