name	transcript-schema
description	Reference for the Claude Code JSONL transcript schema as consumed by Glassbox — the normalized Event model and the (to-be-confirmed) raw field mapping. Read when working on discover.js, read.js, normalize.js, or classify.js. Update the "Confirmed raw schema" section after the Slice 1 discovery spike.

Transcript Schema Reference

The normalized model is the contract. The raw schema below is reverse-engineered and gets confirmed by the discovery spike (see PROGRESS.md). Until confirmed, treat raw fields as best-effort and degrade gracefully.

Normalized `Event` (the contract — TSD §3.1)

Event {
  seq        number        // monotonic 0-based, arrival order
  ts         ?string       // ISO-8601 or null
  type       'user' | 'assistant' | 'tool_call' | 'tool_result' | 'system' | 'unknown'
  text       ?string       // message text for user/assistant
  tool       ?ToolCall     // when type === 'tool_call'
  result     ?ToolResult   // when type === 'tool_result'
  toolUseId  ?string       // correlates result -> call
  raw        object        // original parsed JSON (debugging only)
  warnings   string[]      // non-fatal normalization notes
}

ToolCall   { name, category, input, targets[], command? }
ToolResult { ok?, exitCode?, text, isError }

Normalization rules

Type inference order: explicit role/type field → tool-use block present → tool-result block present → fallback unknown (+warning).
One raw record may expand into multiple Events: an assistant record with text and tool-use blocks becomes an assistant-text Event followed by one tool_call Event per block, preserving seq. Required for accurate metric counting.
Timestamp: read from timestamp / ts / created_at; null if none.
Correlation: match tool_result to its tool_call via toolUseId when present.
All schema knowledge stays in normalize.js.

Classification (TSD §4)

Name table first (lowercased, MCP prefixes stripped), exact → regex fallback.
verify via command sniffing on shell runners (npm/pnpm/yarn (run) test|lint|build, pytest|jest|vitest|tsc|eslint|go test|cargo test|build, npx tsc|eslint|vitest|jest).
Target extraction from input.path|file_path|filePath|targets[]|files[] and *path fields; normalize to POSIX, make workspace-relative when root known.
Semantic detection: names like listcodeusages, *definition*, *references*, documentsymbol, workspacesymbol, hover, *lsp*. If none ever appear → BR-04 runs text-search-only (ASM-04).

Confirmed raw schema (fill after discovery spike)

Concept	Raw field(s)	Confirmed?
record role/type	TBD	⬜
tool name	TBD	⬜
tool input	TBD	⬜
tool result / success signal	TBD	⬜
toolUseId correlation	TBD	⬜
timestamp	TBD	⬜
semantic tool names present	TBD (or none → text-search-only)	⬜

Transcript Schema Reference

The normalized model is the contract. The raw schema below is reverse-engineered and gets confirmed by the discovery spike (see PROGRESS.md). Until confirmed, treat raw fields as best-effort and degrade gracefully.

Normalized Event (the contract — TSD §3.1)

Event { seq number // monotonic 0-based, arrival order ts ?string // ISO-8601 or null type 'user' | 'assistant' | 'tool_call' | 'tool_result' | 'system' | 'unknown' text ?string // message text for user/assistant tool ?ToolCall // when type === 'tool_call' result ?ToolResult // when type === 'tool_result' toolUseId ?string // correlates result -> call raw object // original parsed JSON (debugging only) warnings string[] // non-fatal normalization notes } ToolCall { name, category, input, targets[], command? } ToolResult { ok?, exitCode?, text, isError }

Normalization rules

Type inference order: explicit role/type field → tool-use block present → tool-result block present → fallback unknown (+warning).

One raw record may expand into multiple Events: an assistant record with text and tool-use blocks becomes an assistant-text Event followed by one tool_call Event per block, preserving seq. Required for accurate metric counting.

Timestamp: read from timestamp / ts / created_at; null if none.

Correlation: match tool_result to its tool_call via toolUseId when present.

All schema knowledge stays in normalize.js.

Classification (TSD §4)

Name table first (lowercased, MCP prefixes stripped), exact → regex fallback.

Target extraction from input.path|file_path|filePath|targets[]|files[] and *path fields; normalize to POSIX, make workspace-relative when root known.

Semantic detection: names like listcodeusages, *definition*, *references*, documentsymbol, workspacesymbol, hover, *lsp*. If none ever appear → BR-04 runs text-search-only (ASM-04).

Confirmed raw schema (fill after discovery spike)

Concept

Raw field(s)

Confirmed?

record role/type

TBD

⬜

tool name

TBD

⬜

tool input

TBD

⬜

tool result / success signal

TBD

⬜

toolUseId correlation

TBD

⬜

timestamp

TBD

⬜

semantic tool names present

TBD (or none → text-search-only)

⬜

transcript-schema