Module schema_compat 

Suite-wide trace and evidence schema compatibility (bd-ehk.3).

Centralizes schema version constants for all FrankenTUI trace and evidence formats, and provides a compatibility checker that validates reader/writer version pairs.

Schema Kinds

Kind	Current Version	Format
Evidence	ftui-evidence-v2	JSONL
RenderTrace	render-trace-v1	JSONL
EventTrace	event-trace-v1	JSONL.gz
GoldenTrace	golden-trace-v1	JSONL
Telemetry	1.0.0	OTLP
MigrationIr	migration-ir-v1	JSON

Compatibility Rules

• Exact: reader version == writer version → always compatible.
• Forward: reader is newer than writer → compatible (reader can understand older formats).
• Backward: writer is newer than reader → incompatible (reader cannot understand newer formats without migration).
• Unknown: version string doesn’t match the expected prefix for its schema kind → incompatible.

Tracing

Every compatibility check emits a trace.compat_check span with fields: schema_version, reader_version, writer_version, compatible. Incompatible checks log at ERROR level.

Metrics

Incompatible checks increment trace_compat_failures_total via BuiltinCounter::TraceCompatFailuresTotal.

Structs

CompatCheckResult

Full result of a schema compatibility check, including metadata.

MatrixEntry

Entry in the compatibility matrix, pairing a schema kind with a writer version and expected outcome.

Enums

Compatibility

Outcome of a schema compatibility check.

SchemaKind

All schema kinds in the FrankenTUI suite.

Functions

check_event_trace_compat

Convenience: check event-trace schema compatibility.

check_evidence_compat

Convenience: check evidence schema compatibility.

check_golden_trace_compat

Convenience: check golden-trace schema compatibility.

check_render_trace_compat

Convenience: check render-trace schema compatibility.

check_schema_compat

Check compatibility between a reader (current) and writer version.

default_compatibility_matrix

Build the default compatibility matrix covering all schema kinds.

run_compatibility_matrix

Run the full compatibility matrix and return all results.