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.

Install

moon add SCL-NN/moontracekit

Minimal Example

import "SCL-NN/moontracekit"

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

println(buffer.to_json())

Verify from a clone

moon fmt --check
moon check --target all
moon build --target all
moon test --target all
moon info && git diff --exit-code -- '*.mbti'
moon run cmd/main

On toolchains that expose --deny-warn, use moon fmt --deny-warn and moon info --deny-warn. MoonBit 0.10.4 uses the checked format and generated metadata-diff commands shown above.

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.
• Consumers that need bounded out-of-order buffering and an explicit overflow metric rather than unbounded memory growth.
• 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. A full buffer rejects a newly pending event and increments dropped_count; it does not silently evict existing causal dependencies. Callers must apply their own retry or backpressure policy.

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.