{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://trace.ai/schema/reasoning_trace/v0.2.json",
  "title": "Reasoning Trace",
  "description": "Canonical multimodal process trace of a single cognitive session. Versions 0.2 and 0.2.1 both accepted. 0.2 added parent_session_id and order for cross-session references (second-order traces). 0.2.1 (backward-compatible) adds three problem-scale event types (obstruction, pivot, decisive_insight) and optional per-event id + causes fields for DAG-shaped retrospective traces. See docs/DISCOVERY_TRACES.md.",
  "type": "object",
  "required": ["session_id", "schema_version", "subject", "stimulus", "started_at", "ended_at", "events"],
  "additionalProperties": false,
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Short human-friendly id, e.g. '7f3a' or '7f3b'. Also acts as the directory name under data/.",
      "pattern": "^[a-z0-9_]{3,32}$"
    },
    "schema_version": {
      "type": "string",
      "enum": ["0.2", "0.2.1"]
    },
    "parent_session_id": {
      "type": "string",
      "description": "If this session was produced with awareness of, or in reference to, a prior session, its id goes here. Enables cross-session self-corrections and second-order traces.",
      "pattern": "^[a-z0-9_]{3,32}$"
    },
    "order": {
      "type": "integer",
      "minimum": 1,
      "description": "1 = first-order (subject engages a stimulus). 2 = second-order (subject engages own prior trace as the stimulus, produced with explicit awareness of being a trace subject). 3+ reserved. Default 1 if omitted."
    },
    "subject": {
      "type": "object",
      "required": ["id"],
      "additionalProperties": false,
      "properties": {
        "id": { "type": "string", "description": "Opaque subject id; do not embed PII." },
        "kind": { "enum": ["human", "model", "hybrid"] },
        "notes": { "type": "string" }
      }
    },
    "stimulus": {
      "type": "object",
      "required": ["kind", "content"],
      "additionalProperties": false,
      "properties": {
        "kind": {
          "enum": [
            "text",
            "image",
            "audio",
            "poem",
            "arithmetic",
            "recall_task",
            "translation",
            "open_prompt",
            "other"
          ]
        },
        "content": {
          "type": "string",
          "description": "Verbatim stimulus, or an in-repo path when the stimulus is binary."
        },
        "source": {
          "type": "string",
          "description": "Where the stimulus came from (e.g. 'google_translate:marathi_poetry')."
        },
        "language": { "type": "string" },
        "notes": { "type": "string" }
      }
    },
    "started_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 with timezone. First observable action of the session."
    },
    "ended_at": {
      "type": "string",
      "format": "date-time"
    },
    "context": {
      "type": "object",
      "description": "Ambient context the subject was in. All optional.",
      "additionalProperties": true,
      "properties": {
        "location": { "type": "string" },
        "device": { "type": "string" },
        "wake_state": { "enum": ["awake", "drowsy", "sleep_deprived", "intoxicated", "other"] },
        "companions": { "type": "array", "items": { "type": "string" } }
      }
    },
    "channels": {
      "type": "object",
      "description": "Declaration of which continuous channels are captured, with references to their binary blobs.",
      "additionalProperties": false,
      "properties": {
        "audio_inner_speech": { "$ref": "#/$defs/channel_ref" },
        "audio_environment":  { "$ref": "#/$defs/channel_ref" },
        "keystroke_stream":   { "$ref": "#/$defs/channel_ref" },
        "screen_capture":     { "$ref": "#/$defs/channel_ref" },
        "gaze":               { "$ref": "#/$defs/channel_ref" },
        "affect_signals":     { "$ref": "#/$defs/channel_ref" }
      }
    },
    "events": {
      "type": "array",
      "description": "Time-ordered discrete events. Not exhaustive of everything captured; the continuous channels are the substrate.",
      "items": { "$ref": "#/$defs/event" }
    },
    "self_representation": {
      "type": "array",
      "description": "The R_t layer: compressed, structured self-summaries the subject reports at chosen moments. See FOUNDING_BRIEF §3 for formal semantics.",
      "items": { "$ref": "#/$defs/self_rep_snapshot" }
    },
    "final_output": {
      "type": "object",
      "description": "The externally visible product of the session, if any.",
      "additionalProperties": true,
      "properties": {
        "kind": { "type": "string" },
        "content": { "type": "string" },
        "recipient": { "type": "string" }
      }
    },
    "provenance": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "collector": { "type": "string" },
        "collection_method": { "enum": ["self_annotated", "instrumented_app", "hybrid"] },
        "consent": { "type": "string" }
      }
    }
  },
  "$defs": {
    "channel_ref": {
      "type": "object",
      "required": ["path"],
      "additionalProperties": false,
      "properties": {
        "path":       { "type": "string", "description": "Repo-relative path to the binary." },
        "mime":       { "type": "string" },
        "sample_rate":{ "type": "number" },
        "duration_s": { "type": "number" },
        "sha256":     { "type": "string", "pattern": "^[a-f0-9]{64}$" },
        "notes":      { "type": "string" }
      }
    },
    "event": {
      "type": "object",
      "required": ["t", "type"],
      "additionalProperties": false,
      "properties": {
        "t": {
          "type": "string",
          "description": "Wall-clock ISO 8601, OR seconds-from-started_at as a numeric string. One or the other for the whole session."
        },
        "duration_s": { "type": "number" },
        "type": { "$ref": "#/$defs/event_type" },
        "channel": {
          "enum": [
            "perception",
            "inner_speech",
            "recall_attempt",
            "uncertainty_event",
            "self_correction",
            "tool_use",
            "attention_shift",
            "affect",
            "action",
            "meta"
          ]
        },
        "content": { "type": "string", "description": "Human-readable payload of the event." },
        "title":   { "type": "string", "description": "Optional short section-title of the event (v0.2.1, discovery traces)." },
        "id":      { "type": "string", "description": "Optional session-unique event identifier (v0.2.1, discovery traces). Used as the target of `causes` references on later events.", "pattern": "^[a-zA-Z0-9_.-]{1,32}$" },
        "causes":  { "type": "array", "items": { "type": "string" }, "description": "Optional list of prior event ids that produced this event (v0.2.1). Turns the event sequence into a DAG. See docs/DISCOVERY_TRACES.md." },
        "target":  { "type": "string", "description": "What the event was about (e.g. previous event id, a token span in content)." },
        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
        "tool": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "name":   { "type": "string" },
            "query":  { "type": "string" },
            "result": { "type": "string" }
          }
        },
        "audio_ref": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "channel": { "type": "string" },
            "t_start_s": { "type": "number" },
            "t_end_s":   { "type": "number" }
          }
        },
        "notes": { "type": "string" }
      }
    },
    "event_type": {
      "enum": [
        "session_start",
        "stimulus_presented",
        "recall_attempt",
        "recall_success",
        "recall_partial",
        "self_correction",
        "cross_session_self_correction",
        "tool_use",
        "uncertainty_event",
        "attention_shift",
        "affect_shift",
        "inner_speech",
        "action",
        "clock_check",
        "session_end",
        "meta",
        "meta_frame",
        "linguistic_claim",
        "directive_to_consumer",
        "obstruction",
        "pivot",
        "decisive_insight"
      ]
    },
    "self_rep_snapshot": {
      "type": "object",
      "required": ["t", "r"],
      "additionalProperties": false,
      "properties": {
        "t": { "type": "string" },
        "r": {
          "type": "object",
          "description": "The subject's structured self-representation at time t. Free-form for v0.1; will be constrained in v0.2.",
          "additionalProperties": true,
          "properties": {
            "goal":           { "type": "string" },
            "belief_about_task": { "type": "string" },
            "belief_about_self": { "type": "string" },
            "uncertainty":    { "type": "number", "minimum": 0, "maximum": 1 },
            "planned_next":   { "type": "string" }
          }
        },
        "elicitation": {
          "enum": ["self_report", "probe", "reconstructed"]
        },
        "notes": { "type": "string" }
      }
    }
  }
}