🥮 mooncakes.io

moontracekit

Logical clocks, vector clocks, happens-before analysis, and causal buffers for MoonBit.

causality
vector-clock
lamport-clock
distributed
happens-before
moon add SCL-NN/moontracekit@0.2.0
Download zip
Author
Version
0.2.0
License
Apache-2.0
Repository
Last updated
29 days ago
Downloads
3
README

#MoonTraceKit

MoonTraceKit is a MoonBit foundation library for causal reasoning in distributed systems.

It provides Lamport clocks, vector clocks, happens-before comparison, concurrent event detection, causal frontier calculation, and a causal delivery buffer for out-of-order messages.

#Highlights

  • 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 their dependencies are delivered.
  • Bounded CausalBuffer: capacity control and explicit dropped-event metrics.
  • Analysis helpers: concurrent-pair discovery and frontier calculation.
  • JSON export: stable summaries for demos, logs, and tests.
  • Backend-neutral: no networking, database, browser, or IO dependency.

#Example

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

MoonTraceKit is not a CRDT implementation and not a message queue. It provides the reusable causality semantics that those higher-level systems can compose.

#Install

moon add SCL-NN/moontracekit

For the full project overview, scenarios, boundaries, and run commands, see README.md.

#
CausalBuffer

source
pub(all) struct CausalBuffer {
  delivered : VectorClock
  pending : Array[CausalEvent]
  max_pending : Int
  dropped : Int
}

#
CausalBuffer::deliver

source
fn CausalBuffer::deliver(self : CausalBuffer, event : CausalEvent) -> CausalBuffer

#
CausalBuffer::dropped_count

source
fn CausalBuffer::dropped_count(self : CausalBuffer) -> Int

#
CausalBuffer::flush_ready

source
fn CausalBuffer::flush_ready(self : CausalBuffer) -> CausalBuffer

#
CausalBuffer::new

source

#
CausalBuffer::pending_count

source
fn CausalBuffer::pending_count(self : CausalBuffer) -> Int

#
CausalBuffer::push

source
fn CausalBuffer::push(self : CausalBuffer, event : CausalEvent) -> CausalBuffer

#
CausalBuffer::ready

source
fn CausalBuffer::ready(self : CausalBuffer, event : CausalEvent) -> Bool

#
CausalBuffer::to_json

source
fn CausalBuffer::to_json(self : CausalBuffer) -> String

#
CausalBuffer::with_capacity

source
fn CausalBuffer::with_capacity(max_pending : Int) -> CausalBuffer

Creates a bounded buffer. When full, a newly pending event is rejected and dropped_count records the overflow; callers can use it for backpressure.

#
CausalBuffer::with_delivered

source
fn CausalBuffer::with_delivered(delivered : VectorClock) -> CausalBuffer

#
CausalEvent

source
pub(all) struct CausalEvent {
  id : String
  origin : String
  clock : VectorClock
  payload : String
}

#
CausalEvent::new

source
fn CausalEvent::new(id : String, origin : String, clock : VectorClock, payload : String) -> CausalEvent

#
CausalEvent::to_json

source
fn CausalEvent::to_json(self : CausalEvent) -> String

#
CausalOrder

source
pub(all) enum CausalOrder {
  Equal
  Before
  After
  Concurrent
} derive(Eq, 
Debug)

#
CausalOrder::name

source
fn CausalOrder::name(self : CausalOrder) -> String

#
CausalPair

source
pub(all) struct CausalPair {
  left : String
  right : String
  order : CausalOrder
}

#
CausalPair::new

source
fn CausalPair::new(left : String, right : String, order : CausalOrder) -> CausalPair

#
CausalPair::to_json

source
fn CausalPair::to_json(self : CausalPair) -> String

#
ClockEntry

source
pub(all) struct ClockEntry {
  node : String
  counter : Int
}

#
ClockEntry::new

source
fn ClockEntry::new(node : String, counter : Int) -> ClockEntry

#
ClockEntry::to_json

source
fn ClockEntry::to_json(self : ClockEntry) -> String

#
LamportClock

source
pub(all) struct LamportClock {
  node : String
  counter : Int
}

#
LamportClock::event

source
fn LamportClock::event(self : LamportClock, id : String, payload : String) -> CausalEvent

#
LamportClock::new

source
fn LamportClock::new(node : String) -> LamportClock

#
LamportClock::observe

source
fn LamportClock::observe(self : LamportClock, remote_counter : Int) -> LamportClock

#
LamportClock::tick

source

#
VectorClock

source
pub(all) struct VectorClock {
  entries : Array[ClockEntry]
}

#
VectorClock::compare

source
fn VectorClock::compare(self : VectorClock, other : VectorClock) -> CausalOrder

#
VectorClock::concurrent_with

source
fn VectorClock::concurrent_with(self : VectorClock, other : VectorClock) -> Bool

#
VectorClock::from_entries

source
fn VectorClock::from_entries(entries : Array[ClockEntry]) -> VectorClock

#
VectorClock::get

source
fn VectorClock::get(self : VectorClock, node : String) -> Int

#
VectorClock::happens_before

source
fn VectorClock::happens_before(self : VectorClock, other : VectorClock) -> Bool

#
VectorClock::merge

source
fn VectorClock::merge(self : VectorClock, other : VectorClock) -> VectorClock

#
VectorClock::new

source

#
VectorClock::set

source
fn VectorClock::set(self : VectorClock, node : String, counter : Int) -> VectorClock

#
VectorClock::tick

source
fn VectorClock::tick(self : VectorClock, node : String) -> VectorClock

#
VectorClock::to_json

source
fn VectorClock::to_json(self : VectorClock) -> String

#
causal_frontier

source
fn causal_frontier(events : Array[CausalEvent]) -> VectorClock

#
compare_events

source
fn compare_events(left : CausalEvent, right : CausalEvent) -> CausalPair

#
find_concurrent_pairs

source
fn find_concurrent_pairs(events : Array[CausalEvent]) -> Array[CausalPair]

#
sample_concurrent_events

source
fn sample_concurrent_events() -> Array[CausalEvent]

#
sample_linear_events

source
fn sample_linear_events() -> Array[CausalEvent]

#
sample_out_of_order_events

source
fn sample_out_of_order_events() -> Array[CausalEvent]

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io