# Query Tracing

Every context query produces trace entries that record what was accessed, when, and by what version. Traces provide a provenance chain from knowledge through to agent action.

## What is traced

| Field | Description |
|-------|-------------|
| `document_id` | Which document was accessed |
| `version` | Which version was served |
| `checkpoint` | The checkpoint at the time of access |
| `accessed_at` | Timestamp |
| `selector` | The query that triggered this access |
| `result_hash` | SHA-256 hash of the returned content |

## Source node traces

Source node traces include additional fields:

| Field | Description |
|-------|-------------|
| `transport` | Transport type used (mcp, rest, cli, file) |
| `server` | Server name |
| `tool` | Tool name called |
| `cache_hit` | Whether the result was served from cache |
| `cache_age` | Age of cached result in seconds |

## Provenance chain

Traces enable full provenance reconstruction:

> "The agent resolved `pack:sprint.standup` → read 3 static docs at checkpoint 12 → hydrated `sources/current-sprint-tickets` via Jira MCP (cache miss, result hash `sha256:9f1b...`) → hydrated `sources/recent-pr-activity` via GitHub MCP (cache hit, 4m old) → generated summary."

## Design note

The trace records `result_hash`, not `result_content`. The trace proves **what was seen** without storing the full payload in the vault. Implementations requiring full result retention for compliance should store results in an external audit log.