Reasoning Trace Schema

v0.2 · JSON Schema draft-2020-12 · download · github

A Reasoning Trace is a single cognitive session, keyed by session_id, with time-aligned events across multimodal channels plus optional structured self-representation snapshots. It is the primary training substrate of Trace AI's framework. This page is the field-by-field reference.

Top-level shape

{
  "session_id":       "7f3a",           // ^[a-z0-9_]{3,32}$
  "schema_version":   "0.2",            // required, currently "0.2"
  "parent_session_id":"7f3a",           // optional, links to a prior session
  "order":            1,                // 1 first-order, 2 second, 3 third+ (default 1)
  "subject":          { ... },          // required
  "stimulus":         { ... },          // required
  "started_at":       "2026-07-30T…",   // ISO 8601 with TZ, required
  "ended_at":         "2026-07-30T…",   // ISO 8601 with TZ, required
  "context":          { ... },          // optional
  "channels":         { ... },          // continuous stream declarations
  "events":           [ ... ],          // required, time-ordered discrete events
  "self_representation": [ ... ],       // optional, r_t snapshots
  "final_output":     { ... },          // optional
  "provenance":       { ... }           // required in practice
}

subject

Opaque identity + kind. Do not put PII in subject.id.

{ "id": "s001", "kind": "human", "notes": "…" }

kind ∈ {"human", "model", "hybrid"}. The 7f3c model-authored trace has "kind": "model".

stimulus

What was presented, in the modality it arrived in.

{
  "kind":     "poem",                                      // enum below
  "content":  "कशा आलास दराोहरात, …",                       // verbatim, or path if binary
  "source":   "google_translate:marathi_poetry",           // provenance
  "language": "mr-Deva",                                   // BCP-47 or "auto"
  "notes":    "…"
}

kind ∈ {"text", "image", "audio", "poem", "arithmetic", "recall_task", "translation", "open_prompt", "other"}.

channels

Declaration of continuous streams captured for the session. Each entry references a binary by repo-relative path with mime, sample rate, duration, sha256.

{
  "audio_inner_speech": {
    "path":       "data/session_7f3a/audio/new_recording_168.m4a",
    "mime":       "audio/mp4",
    "sample_rate": 48000,
    "duration_s":  15.168,
    "sha256":      "0a9a7ac6…",
    "notes":       "mono, iOS Voice Memos"
  }
}

Canonical channel keys: audio_inner_speech, audio_environment, keystroke_stream, screen_capture, gaze, affect_signals. Add more when a real session needs them; version bump the schema first.

events

Time-ordered discrete events. Each has a wall-clock timestamp or seconds-from-start, a type from the vocabulary below, a channel label, and content.

{
  "t":          "2026-07-30T03:24:00-04:00",     // ISO 8601 with TZ
  "duration_s": 4,                                // optional
  "type":       "tool_use",                       // event_type vocabulary
  "channel":    "tool_use",                       // channel vocabulary
  "content":    "Looked back at Google Translate to verify spelling.",
  "target":     "stimulus:transliteration",       // optional pointer
  "confidence": 0.92,                             // optional [0,1]
  "tool": { "name": "google_translate", "query": "check spelling", "result": "confirmed" },
  "audio_ref": { "channel": "audio_inner_speech", "t_start_s": 12.3, "t_end_s": 15.1 },
  "notes":      "First tool_use triggered by an internal uncertainty signal."
}

Event type vocabulary (v0.2)

Type	Meaning
session_start	The session begins.
stimulus_presented	The subject is exposed to the stimulus.
recall_attempt	Subject attempts to retrieve content from memory.
recall_success	A recall attempt succeeds fully.
recall_partial	A recall attempt succeeds partially.
self_correction	Subject corrects a prior action or belief.
cross_session_self_correction	Self-correction whose `target` lives in a different session.
tool_use	Subject invokes or observes an external tool.
uncertainty_event	Subject explicitly reports uncertainty.
attention_shift	Focal attention pivots.
affect_shift	Emotional register shifts.
inner_speech	Subject reports or emits inner speech (typically references an audio channel).
action	Subject produces an externally visible output.
clock_check	Subject checks the time; often precedes a temporal self-correction.
session_end	The session ends.
meta	Catch-all for meta-observations that don't fit elsewhere.
meta_frame	Subject names the frame the current recording sits inside.
linguistic_claim	Subject makes a first-person claim about what language can or cannot do.
directive_to_consumer	Subject explicitly instructs the downstream reader/model how to interpret the trace.

Channel vocabulary

Channel	Meaning
perception	External observation surfaced to the subject.
inner_speech	Voiced or subvocal internal narrative.
recall_attempt	Memory-retrieval activity.
uncertainty_event	Explicit uncertainty markers.
self_correction	Corrections of prior actions or beliefs.
tool_use	Interactions with external tools.
attention_shift	Focus pivots.
affect	Emotional signal.
action	Externally visible outputs.
meta	Session-scoped meta-observations.

self_representation

A sequence of snapshots of the subject's compressed self-representation r_t. Populates the training target for L_selfrep and grounds the interventional class for L_gov.

{
  "t":  "2026-07-30T03:29:00-04:00",
  "r": {
    "goal":             "Demonstrate the trace-collection premise.",
    "belief_about_task":"In progress; already achieved the proof.",
    "belief_about_self":"A conscious agent whose per-glyph recognition is not visible in the artifact.",
    "uncertainty":      0.2,
    "planned_next":     "Continue annotating; introduce meta-observations."
  },
  "elicitation": "self_report",   // "self_report" | "probe" | "reconstructed"
  "notes":       "…"
}

parent_session_id and order

New in v0.2. Distinguishes trace kinds:

order 1 — first-order: subject engages an external stimulus. (7f3a)
order 2 — second-order: subject engages own prior trace, with awareness of being a trace subject. (7f3b)
order 3 — third-order: a consumer of a trace (typically a model directed by the subject to produce a trace in the subject's register) becomes itself a trace subject. (7f3c)

Use parent_session_id to point at the prior session that motivated this one. Enables cross_session_self_correction events whose target lives in a different timeline.

Migration from v0.1

# One-shot for any pre-v0.2 trace:
python3 -c "
import json, sys
p = sys.argv[1]
d = json.load(open(p))
d['schema_version'] = '0.2'
d.setdefault('order', 1)
open(p, 'w').write(json.dumps(d, indent=2, ensure_ascii=False) + '\n')
" data/session_XXXX/trace_XXXX.json

Example

The canonical reference example is Session 7f3a: trace_7f3a.json. See it rendered as a browsable timeline on the reference corpus page.

Design principle for the schema: the schema follows the data. Do not add channels or event types casually. Every addition must be justified by a real session that the existing vocabulary cannot represent, and must be documented in CHANGELOG.md.