katra-trace — the Katra trace format.

A trace is a versioned, deterministic, append-only stream of records:

[magic: 8 bytes] [format_version: u32] [header_len: u32] [header: bincode]
[record_len: u32] [record: bincode(TraceRecord)] ... (repeat)

Records are Event, EpochMarker, Counter, or SessionSummary.

Determinism

• seq is monotonic; events are written in seq order.
• Timestamps are ns since profiler start (plus a wall-clock anchor in the header and in epoch markers).
• Replay can therefore re-emit a trace at exact relative timing.

Versioning discipline

• Enum layouts are serialized by variant index: append new variants at the end of any enum in katra-core.
• Any layout-affecting change bumps [header::SCHEMA_HASH] (computed from [header::SCHEMA_STRING] at compile time).
• Backward-incompatible changes bump [header::FORMAT_VERSION].