Merge pull request #2910 from alectimison-maker/feat/trace-otlp-session-association

feat(trace-export): add session-aware OTLP export compatibility

Author: esokullu

docs/export-and-workflow-formats.md

@@ -103,10 +103,17 @@ npm run trace:otlp -- webbrain-trace-example.json \
   --output webbrain-trace-example.otlp.json
 ```
 
+For a legacy single-run input, the output retains the existing root span with
+model-call and tool child spans. A session bundle uses one trace per persisted
+session, one span per run, same-session `parentRunId` parent links, and span
+events for turn/step activity. Cross-session parents are represented as span
+links rather than parent spans.
+
 The output is an
 [OTLP/HTTP JSON](https://opentelemetry.io/docs/specs/otlp/#json-protobuf-encoding)
-`ExportTraceServiceRequest`. It contains one `invoke_agent WebBrain` root span,
-child model-call and `execute_tool` spans, and lightweight lifecycle events.
+`ExportTraceServiceRequest`. Legacy input contains one `invoke_agent WebBrain`
+root span, child model-call and `execute_tool` spans, and lightweight lifecycle
+events; session bundles contain one `invoke_agent` span per run.
 The mappings follow the current
 [OpenTelemetry GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md),
 which are still marked development and may change.
@@ -134,6 +141,10 @@ npm run trace:otlp -- webbrain-trace-example.json \
   --include-content
 ```
 
+See [`trace-format-compatibility.md`](trace-format-compatibility.md) for the
+relationship between the storage version, run format version, and export
+schema, plus the reader obligations for unknown events and legacy records.
+
 This is a post-run conversion, not live OpenTelemetry instrumentation. Child
 span start times are reconstructed from the recorder's completion timestamp and
 reported latency, so they should be used for diagnostics rather than

docs/trace-format-compatibility.md

@@ -0,0 +1,36 @@
+# Trace format compatibility
+
+WebBrain trace data has three independent version layers:
+
+- `DB_VERSION` describes IndexedDB object-store structure and changes only when
+  stores or indexes change.
+- `traceFormatVersion` describes the meaning of a persisted run and its event
+  log. New optional fields and new event kinds are additive and remain at the
+  current version. Bump this value only when an existing meaning changes, a
+  field becomes required, or `seq`/`ts` semantics change.
+- `schema` describes the JSON export envelope. `webbrain-trace/1` remains the
+  envelope for additive run and event changes. A new schema is reserved for a
+  container-shape or semantic break.
+
+## Reader obligations
+
+Treat a missing or malformed `traceFormatVersion` as the legacy baseline. Keep
+missing optional fields harmless. Reject a numeric `traceFormatVersion` newer
+than the latest version the reader supports instead of interpreting `seq` and
+`ts` with older semantics. Readers must not fail an entire export because one
+event kind is unknown:
+
+- the Traces UI shows a labeled placeholder with the raw event view;
+- machine-readable exporters preserve an unknown event as a generic record with
+  its event kind;
+- the Markdown summary may omit unknown event details, but reports the count.
+
+Raw JSON re-export keeps the original fields. Compatibility handling does not
+perform destructive migration and does not change the default privacy policy.
+
+## Session bundles
+
+The existing single-run `webbrain-trace/1` shape remains valid. A session bundle
+may carry a `session` identity and a `runs` array containing `{ run, events }`
+entries. Session-aware consumers use persisted `conversationId`, `parentRunId`,
+and `parentSessionId` values; they do not infer lineage from in-memory state.