MoonTraceKit

MoonTraceKit is a MoonBit foundation library for causal event traces.

It provides Lamport clocks, vector clocks, happens-before analysis, concurrent event detection, causal frontier calculation, and out-of-order causal delivery buffers.

What It Solves

MoonTraceKit helps MoonBit programs answer questions that wall-clock timestamps cannot answer safely:

• Did event A definitely happen before event B?
• Are two edits concurrent and therefore candidates for conflict handling?
• Can an out-of-order message be delivered now, or is a dependency missing?
• What is the causal frontier after replaying a group of events?
• Which event pairs should be inspected before merging offline work?

Not a Duplicate of Tracing SDKs

MoonTraceKit is deliberately not an observability tracing SDK.

• It is not an OpenTelemetry exporter.
• It is not a span collector.
• It is not a logging framework.
• It is not a complete CRDT framework.

The word Trace here means an event’s causal trace: the logical relationship between events in distributed or offline-first systems. Observability tracing tools describe request paths; MoonTraceKit describes causality.

Core API

• LamportClock: local tick, remote observation, and event creation.
• VectorClock: set, tick, merge, compare, happens-before, concurrency.
• CausalEvent: event id, origin node, payload, and vector clock.
• CausalBuffer: hold messages until causal dependencies are delivered.
• find_concurrent_pairs: find event pairs that are concurrent.
• causal_frontier: merge event clocks into one frontier.
• to_json: export stable summaries for demos, logs, and tests.

Minimal Example

let events = sample_out_of_order_events()
let buffer = CausalBuffer::new()
  .push(events[0])
  .push(events[1])
  .flush_ready()

println(buffer.to_json())

Run

moon check --target all
moon test --target wasm
moon test --target wasm-gc
moon run cmd/main

Scenarios

• Offline editors that need to detect concurrent edits before merging.
• Message consumers that must delay delivery until dependencies arrive.
• Event-sourcing demos that need deterministic replay frontiers.
• Distributed tests that need small, inspectable causal histories.
• CRDT or replication libraries that want reusable vector-clock semantics.

Boundaries

MoonTraceKit does not provide networking, storage replication, CRDT merge policies, wall-clock synchronization, span export, or telemetry collection. It keeps those concerns out so the core causality layer stays small and reusable.

Repository

GitHub and GitLink are mirrors of the same competition project. The repository includes source code, tests, CI, related-work notes, acceptance notes, and a public application summary.