Trace schema
The trace schema is the language CCPA speaks. Everything — the differ, the Arena runner, the replayer — operates on Trace objects: a sequence of Record types each describing one observable action.
The 7 record kinds (schema v2)
| Kind | Fields | When emitted |
|---|---|---|
session_start | session_id, cwd, git_commit | First record of every trace |
user_prompt | text, attachments[] | User-initiated turn |
assistant_turn | text, blocks[], stop_reason | Model response |
tool_result | tool_use_id, content, is_error | Tool execution result |
session_end | reason | Last record (clean shutdown or interrupt) |
hook_event | hook_name, trigger, tool_use_id? | Hook fired (schema v2, M15) |
skill_invocation | skill_name, args | Skill invoked (schema v2, M15) |
assistant_turn.blocks[] is a polymorphic array — each block is one of:
Text { text }— model output textToolUse { id, name, input }— a tool call (Bash,Read,Write,Edit,Glob,Grep,Shell, ...)Thinking { text }— extended thinking (claude-only; optional)
The Rust types are mirrored in crates/ccpa-trace/src/lib.rs; the JSON-schema is in contracts/claude-code-parity-apr-v1.yaml § trace_schema.
File format — JSONL (one record per line)
{"kind":"session_start","session_id":"abc-123","cwd":"/tmp/fixture-0001","git_commit":"deadbeef"}
{"kind":"user_prompt","text":"Fix the failing test."}
{"kind":"assistant_turn","blocks":[{"type":"text","text":"I'll start by reading the file."},{"type":"tool_use","id":"tu_1","name":"Read","input":{"path":"src/lib.rs"}}],"stop_reason":"tool_use"}
{"kind":"tool_result","tool_use_id":"tu_1","content":"<file contents>","is_error":false}
...
{"kind":"session_end","reason":"end_turn"}
JSONL means line-oriented, append-only, streamable. The parser at ccpa-trace::parse::parse_file is O(n) and emits structured errors with line numbers.
Roundtrip falsifier — FALSIFY-CCPA-001
Every record kind has a roundtrip test: serialize → parse → re-serialize → compare. If any field is lossy or any field re-orders, the roundtrip falsifier catches it.
17 pin tests in crates/ccpa-trace/tests/falsify_ccpa_001_roundtrip.rs.
Schema versioning
- v1 (M0-M14): 5 record kinds (
session_start,user_prompt,assistant_turn,tool_result,session_end). - v2 (M15+): adds
hook_eventandskill_invocation. The differ's hook/skill projection rules require these.
Schema bumps follow the Methodology cycle — contract YAML first, then tests, then code.