Module merge 

Union-merge logic for bones event shard files.

This module implements the core merge operation used by both the git merge driver (bn merge-driver) and any other sync path that needs to combine two sets of TSJSON events into a single canonical, deduplicated, ordered sequence.

Merge Semantics

Bones .events files are append-only CRDT logs. A merge is always safe: take the union of both sides, deduplicate by content hash, and sort deterministically. No event is ever lost; no event appears twice.

Sort Order

Events are ordered by (wall_ts_us, agent, event_hash) — all ascending. This order is:

• Deterministic: given the same set of events, the output is always identical regardless of which replica produced it.
• Causal-ish: wall-clock timestamps order events that happened at different times; the agent + hash tiebreakers make concurrent events stable.

Note that wall-clock timestamps can drift across agents. For strict causal ordering, callers should use the ITC stamps; the sort here is only for canonical file ordering.

Structs

MergeResult

The result of merging two event sets.

Functions

merge_event_sets

Merge two sets of events using union-merge (CRDT join) semantics.