fix(protocol): align trace schemas with v2/v3 classify rules

RecordedTrace validation now follows classify_value — numeric version
selects v3, otherwise v2 — so mixed pages/states and v2 envelopes with
a version field fail Schema checks before Recall import. Keep standalone
trace_step as a v2|v3 union for tools that validate a single step.

Author: shnpd

apps/extension/src/transport/types.ts

@@ -661,6 +661,7 @@ export interface EmulateResult {
 // --------------------------------------------------------------------------
 
 export const TRACE_VERSION_V3 = 3;
+/** Logical v2 identifier. Not a wire field — v2 envelopes omit `version`. */
 export const TRACE_VERSION_V2 = 2;
 export const VOM_FORMAT_VERSION = 1;
 
@@ -853,6 +854,7 @@ export interface TraceV3 {
 }
 
 export type RecordedTrace = TraceV2 | TraceV3;
+export type RecordedStep = StepV2 | StepV3;
 
 export interface RecordStartParams {
   session_id: string;

crates/bsk-protocol/schema/tool_record_await_result.json

@@ -64,14 +64,22 @@
       }
     },
     "RecordedTrace": {
-      "oneOf": [
-        {
-          "$ref": "#/definitions/TraceV2"
-        },
-        {
-          "$ref": "#/definitions/TraceV3"
+      "if": {
+        "required": [
+          "version"
+        ],
+        "properties": {
+          "version": {
+            "type": "integer"
+          }
         }
-      ]
+      },
+      "then": {
+        "$ref": "#/definitions/TraceV3"
+      },
+      "else": {
+        "$ref": "#/definitions/TraceV2"
+      }
     },
     "RecorderInfo": {
       "type": "object",
@@ -834,7 +842,8 @@
       }
     },
     "TraceV2": {
-      "description": "Persisted user-action trace exported by legacy `tool.record_stop` / `await`.\n\nUnknown extension fields are ignored so older traces remain readable. Mixed v2/v3 envelopes are rejected by `RecordedTrace` classification.",
+      "title": "TraceV2",
+      "description": "Persisted user-action trace exported by legacy `tool.record_stop` / `await`.\n\nUnknown extension fields are ignored so older traces remain readable. `states[]` and a numeric `version` are reserved for Trace v3 / `RecordedTrace` classification.",
       "type": "object",
       "required": [
         "entry",
@@ -868,11 +877,18 @@
             "null"
           ]
         },
+        "states": false,
         "steps": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/StepV2"
           }
+        },
+        "version": {
+          "description": "Numeric version selects Trace v3. Legacy v2 envelopes omit this field.",
+          "not": {
+            "type": "integer"
+          }
         }
       }
     },

crates/bsk-protocol/schema/tool_record_stop_result.json

@@ -64,14 +64,22 @@
       }
     },
     "RecordedTrace": {
-      "oneOf": [
-        {
-          "$ref": "#/definitions/TraceV2"
-        },
-        {
-          "$ref": "#/definitions/TraceV3"
+      "if": {
+        "required": [
+          "version"
+        ],
+        "properties": {
+          "version": {
+            "type": "integer"
+          }
         }
-      ]
+      },
+      "then": {
+        "$ref": "#/definitions/TraceV3"
+      },
+      "else": {
+        "$ref": "#/definitions/TraceV2"
+      }
     },
     "RecorderInfo": {
       "type": "object",
@@ -834,7 +842,8 @@
       }
     },
     "TraceV2": {
-      "description": "Persisted user-action trace exported by legacy `tool.record_stop` / `await`.\n\nUnknown extension fields are ignored so older traces remain readable. Mixed v2/v3 envelopes are rejected by `RecordedTrace` classification.",
+      "title": "TraceV2",
+      "description": "Persisted user-action trace exported by legacy `tool.record_stop` / `await`.\n\nUnknown extension fields are ignored so older traces remain readable. `states[]` and a numeric `version` are reserved for Trace v3 / `RecordedTrace` classification.",
       "type": "object",
       "required": [
         "entry",
@@ -868,11 +877,18 @@
             "null"
           ]
         },
+        "states": false,
         "steps": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/StepV2"
           }
+        },
+        "version": {
+          "description": "Numeric version selects Trace v3. Legacy v2 envelopes omit this field.",
+          "not": {
+            "type": "integer"
+          }
         }
       }
     },

crates/bsk-protocol/schema/trace.json

@@ -1,14 +1,22 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "RecordedTrace",
-  "oneOf": [
-    {
-      "$ref": "#/definitions/TraceV2"
-    },
-    {
-      "$ref": "#/definitions/TraceV3"
+  "if": {
+    "required": [
+      "version"
+    ],
+    "properties": {
+      "version": {
+        "type": "integer"
+      }
     }
-  ],
+  },
+  "then": {
+    "$ref": "#/definitions/TraceV3"
+  },
+  "else": {
+    "$ref": "#/definitions/TraceV2"
+  },
   "definitions": {
     "FillCommit": {
       "type": "string",
@@ -823,7 +831,8 @@
       }
     },
     "TraceV2": {
-      "description": "Persisted user-action trace exported by legacy `tool.record_stop` / `await`.\n\nUnknown extension fields are ignored so older traces remain readable. Mixed v2/v3 envelopes are rejected by `RecordedTrace` classification.",
+      "title": "TraceV2",
+      "description": "Persisted user-action trace exported by legacy `tool.record_stop` / `await`.\n\nUnknown extension fields are ignored so older traces remain readable. `states[]` and a numeric `version` are reserved for Trace v3 / `RecordedTrace` classification.",
       "type": "object",
       "required": [
         "entry",
@@ -857,11 +866,18 @@
             "null"
           ]
         },
+        "states": false,
         "steps": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/StepV2"
           }
+        },
+        "version": {
+          "description": "Numeric version selects Trace v3. Legacy v2 envelopes omit this field.",
+          "not": {
+            "type": "integer"
+          }
         }
       }
     },