merge_machines 0.2.0

data/ext/merge_machines_native/ffi/src/gcounter.rs

@@ -0,0 +1,138 @@
+//! `MergeMachines::GCounter`: a counter that only goes up.
+
+use std::cell::RefCell;
+
+use bytes::Bytes;
+use magnus::scan_args::{get_kwargs, scan_args};
+use magnus::typed_data::Obj;
+use magnus::{Error, RHash, RModule, RString, Ruby, Value, function, method, prelude::*};
+use merge_machines::{GCounter, ReplicaId};
+
+use crate::shape::shaped;
+use crate::{
+    REPLICAS, Whole, blob_shape, capacity, mismatch, required_kwarg, unsupported, unsupported_blob,
+};
+
+/// The counter at a single replica count.
+type Held<const R: usize> = GCounter<R>;
+
+shaped!(Counter over Held { R4 = 4, R8 = 8, R16 = 16, R32 = 32 });
+
+/// Runs `body` against whichever variant is held.
+macro_rules! counter {
+    ($counter:expr, |$inner:ident| $body:expr) => {
+        match $counter {
+            Counter::R4($inner) => $body,
+            Counter::R8($inner) => $body,
+            Counter::R16($inner) => $body,
+            Counter::R32($inner) => $body,
+        }
+    };
+}
+
+#[magnus::wrap(class = "MergeMachines::GCounter", free_immediately, size)]
+struct Wrapper(RefCell<Counter>);
+
+const fn replicas_of<const R: usize>(_: &Held<R>) -> usize {
+    R
+}
+
+impl Wrapper {
+    fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let Whole(replicas): Whole<usize> = required_kwarg(args.keywords, "replicas")?;
+        Ok(Self(RefCell::new(dispatch(ruby, replicas, None)?)))
+    }
+
+    /// Reads a blob written by [`dump`](Self::dump).
+    fn load(ruby: &Ruby, blob: Bytes) -> Result<Self, Error> {
+        let replicas = blob_shape(ruby, &blob)?;
+        Ok(Self(RefCell::new(dispatch(ruby, replicas, Some(&blob))?)))
+    }
+
+    fn replicas(&self) -> usize {
+        counter!(&*self.0.borrow(), |counter| replicas_of(&**counter))
+    }
+
+    /// Adds `by:` to `replica:`'s own count.
+    fn increment(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<(), Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let (replica, by) = increment_args(args.keywords)?;
+        capacity(
+            ruby,
+            counter!(&mut *rb_self.0.borrow_mut(), |counter| counter
+                .increment(replica, by)),
+        )
+    }
+
+    /// What `replica:` has added.
+    fn count(&self, args: &[Value]) -> Result<u64, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let Whole(replica): Whole<ReplicaId> = required_kwarg(args.keywords, "replica")?;
+        Ok(counter!(&*self.0.borrow(), |counter| counter.count(replica)))
+    }
+
+    /// Every replica's count.
+    fn value(&self) -> u128 {
+        counter!(&*self.0.borrow(), |counter| counter.value())
+    }
+
+    fn merge(ruby: &Ruby, rb_self: Obj<Self>, other: &Self) -> Result<Obj<Self>, Error> {
+        let source = other.0.borrow().clone();
+        let Some(folded) = rb_self.0.borrow_mut().absorb(&source) else {
+            return Err(mismatch(ruby, "counter"));
+        };
+        capacity(ruby, folded)?;
+        Ok(rb_self)
+    }
+
+    /// The core frame, tag 0x61.
+    fn dump(ruby: &Ruby, rb_self: &Self) -> RString {
+        let frame = counter!(&*rb_self.0.borrow(), |counter| counter.encoded());
+        ruby.str_from_slice(&frame)
+    }
+
+    fn inspect(&self) -> String {
+        format!(
+            "#<MergeMachines::GCounter replicas={} value={}>",
+            self.replicas(),
+            self.value()
+        )
+    }
+}
+
+/// The `replica:` an increment is credited to and the `by:` it adds.
+pub fn increment_args(keywords: RHash) -> Result<(ReplicaId, u64), Error> {
+    let keywords = get_kwargs::<_, (Whole<ReplicaId>,), (Option<Whole<u64>>,), ()>(
+        keywords,
+        &["replica"],
+        &["by"],
+    )?;
+    let (Whole(replica),) = keywords.required;
+    let (by,) = keywords.optional;
+    Ok((replica, by.map_or(1, |Whole(by)| by)))
+}
+
+/// The variant for `replicas`, read from `blob` when there is one.
+fn dispatch(ruby: &Ruby, replicas: usize, blob: Option<&[u8]>) -> Result<Counter, Error> {
+    let Some(frame) = blob else {
+        return Counter::blank(replicas)
+            .ok_or_else(|| unsupported(ruby, "replicas", replicas, &REPLICAS));
+    };
+    Counter::decoded(ruby, replicas, frame)
+        .unwrap_or_else(|| Err(unsupported_blob(ruby, "replica count", &REPLICAS)))
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("GCounter", ruby.class_object())?;
+    class.define_singleton_method("new", function!(Wrapper::new, -1))?;
+    class.define_singleton_method("load", function!(Wrapper::load, 1))?;
+    class.define_method("replicas", method!(Wrapper::replicas, 0))?;
+    class.define_method("increment", method!(Wrapper::increment, -1))?;
+    class.define_method("count", method!(Wrapper::count, -1))?;
+    class.define_method("value", method!(Wrapper::value, 0))?;
+    class.define_method("merge", method!(Wrapper::merge, 1))?;
+    class.define_method("dump", method!(Wrapper::dump, 0))?;
+    class.define_method("inspect", method!(Wrapper::inspect, 0))?;
+    Ok(())
+}

data/ext/merge_machines_native/ffi/src/gset.rs

@@ -0,0 +1,187 @@
+//! `MergeMachines::GSet`: a set nothing is ever taken out of.
+
+use std::cell::RefCell;
+
+use bytes::Bytes;
+use magnus::scan_args::scan_args;
+use magnus::typed_data::Obj;
+use magnus::{Error, RArray, RHash, RModule, RString, Ruby, Value, function, method, prelude::*};
+use merge_machines::GSet;
+
+use crate::hash::hash64;
+use crate::names::{self, Names};
+use crate::shape::{frame_len_of, shaped};
+use crate::{
+    CAPACITIES, Whole, blob_shape, capacity, mismatch, required_kwarg, unsupported,
+    unsupported_blob,
+};
+
+/// The set at a single capacity, over the 64-bit hash each key becomes.
+type Held<const N: usize> = GSet<u64, N>;
+
+shaped!(Set over Held { N64 = 64, N256 = 256, N1024 = 1024 });
+
+/// Runs `body` against whichever variant is held.
+macro_rules! set {
+    ($set:expr, |$inner:ident| $body:expr) => {
+        match $set {
+            Set::N64($inner) => $body,
+            Set::N256($inner) => $body,
+            Set::N1024($inner) => $body,
+        }
+    };
+}
+
+/// The set counts 64-bit key hashes, and `names` holds the string each one
+/// came from.
+#[magnus::wrap(class = "MergeMachines::GSet", free_immediately, size)]
+struct Wrapper {
+    set: RefCell<Set>,
+    names: RefCell<Names>,
+}
+
+const fn capacity_of<const N: usize>(_: &Held<N>) -> usize {
+    N
+}
+
+impl Wrapper {
+    fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let Whole(capacity): Whole<usize> = required_kwarg(args.keywords, "capacity")?;
+        Ok(Self {
+            set: RefCell::new(dispatch(ruby, capacity, None)?),
+            names: RefCell::new(Names::new()),
+        })
+    }
+
+    /// Reads a blob written by [`dump`](Self::dump).
+    fn load(ruby: &Ruby, blob: Bytes) -> Result<Self, Error> {
+        let set = dispatch(ruby, blob_shape(ruby, &blob)?, Some(&blob))?;
+        let frame_len = set!(&set, |inner| frame_len_of(&**inner));
+        let names = names::read(ruby, &blob[frame_len..])?;
+        let elements = set!(&set, |inner| inner.iter().collect::<Vec<u64>>());
+        names::complete(ruby, &names, elements.into_iter())?;
+
+        let wrapper = Self {
+            set: RefCell::new(set),
+            names: RefCell::new(names),
+        };
+        wrapper.prune();
+        Ok(wrapper)
+    }
+
+    fn capacity(&self) -> usize {
+        set!(&*self.set.borrow(), |set| capacity_of(&**set))
+    }
+
+    /// Adds `key`, which is a no-op if it is already in.
+    fn add(ruby: &Ruby, rb_self: &Self, key: String) -> Result<(), Error> {
+        let element = hash64(key.as_bytes());
+        capacity(
+            ruby,
+            set!(&mut *rb_self.set.borrow_mut(), |set| set.insert(element)),
+        )?;
+        rb_self.names.borrow_mut().insert(element, key);
+        Ok(())
+    }
+
+    fn includes(&self, key: String) -> bool {
+        let element = hash64(key.as_bytes());
+        set!(&*self.set.borrow(), |set| set.contains(&element))
+    }
+
+    /// The keys in the set, in no particular order.
+    fn members(ruby: &Ruby, rb_self: &Self) -> Result<RArray, Error> {
+        let elements = set!(&*rb_self.set.borrow(), |set| set
+            .iter()
+            .collect::<Vec<u64>>());
+        names::members(ruby, &rb_self.names.borrow(), &elements)
+    }
+
+    fn size(&self) -> usize {
+        set!(&*self.set.borrow(), |set| set.len())
+    }
+
+    fn is_empty(&self) -> bool {
+        set!(&*self.set.borrow(), |set| set.is_empty())
+    }
+
+    fn merge(ruby: &Ruby, rb_self: Obj<Self>, other: &Self) -> Result<Obj<Self>, Error> {
+        let source = other.set.borrow().clone();
+        let names = other.names.borrow().clone();
+        let Some(folded) = rb_self.set.borrow_mut().absorb(&source) else {
+            return Err(mismatch(ruby, "set"));
+        };
+        rb_self.names.borrow_mut().extend(names);
+        rb_self.prune();
+        capacity(ruby, folded)?;
+        Ok(rb_self)
+    }
+
+    /// The core frame followed by the names of the keys it holds.
+    ///
+    /// ```text
+    /// core frame   GSet::<u64, capacity>::ENCODED_LEN bytes, tag 0x81
+    /// name record  u64 little-endian byte length, then that many UTF-8 bytes
+    /// ```
+    ///
+    /// One record per key, in the core frame's order, filling the rest of the
+    /// blob. The frame holds 64-bit hashes, so [`load`](Self::load) rehashes
+    /// each name to rebuild what [`members`](Self::members) reads.
+    fn dump(ruby: &Ruby, rb_self: &Self) -> RString {
+        let (frame, elements) = set!(&*rb_self.set.borrow(), |set| (
+            set.encoded(),
+            set.iter().collect::<Vec<u64>>()
+        ));
+        let mut blob = Vec::from(frame);
+        names::write(&mut blob, &rb_self.names.borrow(), elements.into_iter());
+        ruby.str_from_slice(&blob)
+    }
+
+    fn inspect(&self) -> String {
+        format!(
+            "#<MergeMachines::GSet capacity={} size={}>",
+            self.capacity(),
+            self.size()
+        )
+    }
+
+    /// Leaves a name for every key the core holds and for nothing else.
+    ///
+    /// A merge extends the table before the core reports whether everything
+    /// fit, because a merge that overran capacity still took whatever it had
+    /// room for and those keys need their names. Reconciling afterwards keeps
+    /// the names of the keys that landed and drops the ones that did not.
+    fn prune(&self) {
+        let set = self.set.borrow();
+        self.names
+            .borrow_mut()
+            .retain(|element, _| set!(&*set, |held| held.contains(element)));
+    }
+}
+
+/// The variant for `capacity`, read from `blob` when there is one.
+fn dispatch(ruby: &Ruby, capacity: usize, blob: Option<&[u8]>) -> Result<Set, Error> {
+    let Some(frame) = blob else {
+        return Set::blank(capacity)
+            .ok_or_else(|| unsupported(ruby, "capacity", capacity, &CAPACITIES));
+    };
+    Set::decoded(ruby, capacity, frame)
+        .unwrap_or_else(|| Err(unsupported_blob(ruby, "capacity", &CAPACITIES)))
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("GSet", ruby.class_object())?;
+    class.define_singleton_method("new", function!(Wrapper::new, -1))?;
+    class.define_singleton_method("load", function!(Wrapper::load, 1))?;
+    class.define_method("capacity", method!(Wrapper::capacity, 0))?;
+    class.define_method("add", method!(Wrapper::add, 1))?;
+    class.define_method("include?", method!(Wrapper::includes, 1))?;
+    class.define_method("members", method!(Wrapper::members, 0))?;
+    class.define_method("size", method!(Wrapper::size, 0))?;
+    class.define_method("empty?", method!(Wrapper::is_empty, 0))?;
+    class.define_method("merge", method!(Wrapper::merge, 1))?;
+    class.define_method("dump", method!(Wrapper::dump, 0))?;
+    class.define_method("inspect", method!(Wrapper::inspect, 0))?;
+    Ok(())
+}

data/ext/merge_machines_native/ffi/src/hash.rs

@@ -0,0 +1,33 @@
+//! The binding's only hash. The core's elements are `Copy + Eq`, so a Ruby
+//! string crosses as a 64-bit hash of its UTF-8 bytes.
+
+use crate::{FIELD_LEN, field};
+
+const PRIME: u64 = 0x9E37_79B9_7F4A_7C15;
+
+/// `splitmix64`'s finalizer: a bijection on [`u64`].
+const fn mix64(value: u64) -> u64 {
+    let mut z = value.wrapping_add(PRIME);
+    z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+    z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+    z ^ (z >> 31)
+}
+
+/// Hashes bytes, folding [`FIELD_LEN`] at a time through [`mix64`], then the
+/// remainder and the length separately.
+pub fn hash64(bytes: &[u8]) -> u64 {
+    let (lanes, tail) = bytes.as_chunks::<FIELD_LEN>();
+    let mut accumulator = PRIME;
+
+    for lane in lanes {
+        accumulator = (accumulator ^ mix64(u64::from_le_bytes(*lane)))
+            .rotate_left(27)
+            .wrapping_mul(PRIME);
+    }
+
+    let mut last = [0_u8; FIELD_LEN];
+    last[..tail.len()].copy_from_slice(tail);
+    let length = u64::from_le_bytes(field(bytes.len()));
+
+    mix64(mix64(accumulator ^ length.wrapping_mul(PRIME)) ^ mix64(u64::from_le_bytes(last)))
+}

data/ext/merge_machines_native/ffi/src/hybrid.rs

@@ -0,0 +1,110 @@
+//! `MergeMachines::HybridClock`: timestamps near physical time that still
+//! order.
+
+use std::cell::RefCell;
+
+use bytes::Bytes;
+use magnus::scan_args::{get_kwargs, scan_args};
+use magnus::{Error, RHash, RModule, RString, Ruby, Value, function, method, prelude::*};
+use merge_machines::{HybridClock, ReplicaId};
+
+use crate::data::{stamped, timestamp};
+use crate::{
+    Whole, codec_error, exhausted, optional_kwarg, required_kwarg, trailing_replica, wall,
+};
+
+/// A clock and the replica whose events it stamps, which the core does not
+/// hold.
+#[magnus::wrap(class = "MergeMachines::HybridClock", free_immediately, size)]
+struct Wrapper {
+    clock: RefCell<HybridClock>,
+    replica: ReplicaId,
+}
+
+impl Wrapper {
+    fn new(args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let Whole(replica): Whole<ReplicaId> = required_kwarg(args.keywords, "replica")?;
+        Ok(Self {
+            clock: RefCell::new(HybridClock::new()),
+            replica,
+        })
+    }
+
+    /// Reads a blob written by [`dump`](Self::dump).
+    fn load(ruby: &Ruby, blob: Bytes) -> Result<Self, Error> {
+        let mut clock = HybridClock::new();
+        clock
+            .decode_into(&blob)
+            .map_err(|error| codec_error(ruby, error))?;
+
+        Ok(Self {
+            clock: RefCell::new(clock),
+            replica: trailing_replica(ruby, &blob, HybridClock::ENCODED_LEN)?,
+        })
+    }
+
+    const fn replica(&self) -> ReplicaId {
+        self.replica
+    }
+
+    /// The last timestamp this clock issued.
+    fn now(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
+        timestamp(ruby, rb_self.clock.borrow().last())
+    }
+
+    /// Stamps a local event at `wall_ns:`, defaulting to the realtime clock.
+    fn tick(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<Value, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let wall_ns = match optional_kwarg::<Whole<u64>>(args.keywords, "wall_ns")? {
+            Some(Whole(nanoseconds)) => nanoseconds,
+            None => wall::now_ns(ruby)?,
+        };
+        let issued = rb_self.clock.borrow_mut().tick(wall_ns);
+        timestamp(ruby, exhausted(ruby, issued)?)
+    }
+
+    /// Stamps the receipt of the timestamp `wall_ns:` and `counter:` name, at
+    /// the realtime clock's reading.
+    fn observe(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<Value, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let (Whole(wall_ns), Whole(counter)) = get_kwargs::<_, (Whole<u64>, Whole<u64>), (), ()>(
+            args.keywords,
+            &["wall_ns", "counter"],
+            &[],
+        )?
+        .required;
+        let now = wall::now_ns(ruby)?;
+        let observed = stamped(wall_ns, counter);
+        let issued = rb_self.clock.borrow_mut().observe(now, observed);
+        timestamp(ruby, exhausted(ruby, issued)?)
+    }
+
+    /// The core frame followed by the replica id, 64-bit little-endian.
+    fn dump(ruby: &Ruby, rb_self: &Self) -> RString {
+        let mut blob = Vec::from(rb_self.clock.borrow().encoded());
+        blob.extend_from_slice(&rb_self.replica.to_le_bytes());
+        ruby.str_from_slice(&blob)
+    }
+
+    fn inspect(&self) -> String {
+        let last = self.clock.borrow().last();
+        format!(
+            "#<MergeMachines::HybridClock replica={} wall_ns={} counter={}>",
+            self.replica, last.wall_ns, last.counter
+        )
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("HybridClock", ruby.class_object())?;
+    class.define_singleton_method("new", function!(Wrapper::new, -1))?;
+    class.define_singleton_method("load", function!(Wrapper::load, 1))?;
+    class.define_method("replica", method!(Wrapper::replica, 0))?;
+    class.define_method("now", method!(Wrapper::now, 0))?;
+    class.define_method("tick", method!(Wrapper::tick, -1))?;
+    class.define_method("observe", method!(Wrapper::observe, -1))?;
+    class.define_method("dump", method!(Wrapper::dump, 0))?;
+    class.define_method("inspect", method!(Wrapper::inspect, 0))?;
+    Ok(())
+}

data/ext/merge_machines_native/ffi/src/lib.rs

@@ -0,0 +1,221 @@
+//! Ruby bindings for the `merge-machines` replicated states.
+//!
+//! Replica counts and set capacities are const generics, so every class
+//! dispatches the number it is given to a fixed set of monomorphised variants
+//! and raises `ArgumentError` for any other number.
+//!
+//! Wall-clock readings are nanoseconds on both sides of this boundary.
+//! `NS_PER_SECOND` is exposed for callers holding seconds.
+
+#![allow(clippy::needless_pass_by_value)]
+
+mod data;
+mod gcounter;
+mod gset;
+mod hash;
+mod hybrid;
+mod logical;
+mod lww;
+mod names;
+mod orset;
+mod pncounter;
+mod shape;
+mod wall;
+
+use std::sync::OnceLock;
+
+use magnus::scan_args::get_kwargs;
+use magnus::value::Opaque;
+use magnus::{Error, ExceptionClass, Integer, RHash, RModule, Ruby, TryConvert, Value, prelude::*};
+use merge_machines::{CapacityError, ClockExhausted, CodecError, ReplicaId};
+
+/// `MergeMachines::Full`, defined in [`init`].
+static FULL: OnceLock<Opaque<ExceptionClass>> = OnceLock::new();
+
+/// `MergeMachines::Exhausted`, defined in [`init`].
+static EXHAUSTED: OnceLock<Opaque<ExceptionClass>> = OnceLock::new();
+
+/// Nanoseconds in a second.
+pub(crate) const NS_PER_SECOND: u32 = 1_000_000_000;
+
+/// Replica counts the counters are monomorphised for.
+pub(crate) const REPLICAS: [usize; 4] = [4, 8, 16, 32];
+
+/// Capacities the sets are monomorphised for.
+pub(crate) const CAPACITIES: [usize; 3] = [64, 256, 1024];
+
+/// Where a core frame names the shape it was written at.
+pub(crate) const SHAPE: core::ops::Range<usize> = 1..3;
+
+/// Bytes a 64-bit field occupies in a blob.
+pub(crate) const FIELD_LEN: usize = 8;
+
+/// The low [`FIELD_LEN`] bytes of `value`, little-endian.
+pub(crate) fn field(value: usize) -> [u8; FIELD_LEN] {
+    let mut bytes = [0_u8; FIELD_LEN];
+    for (slot, byte) in bytes.iter_mut().zip(value.to_le_bytes()) {
+        *slot = byte;
+    }
+    bytes
+}
+
+/// A whole number of things: a stamp, a replica, a capacity, a counter, a
+/// nanosecond reading.
+///
+/// magnus reads an integer through Ruby's `NUM2*` family, which truncates a
+/// `Float` towards zero instead of refusing it, so an argument that means an
+/// integer is read as one of these and anything but an `Integer` is turned
+/// away. An `Integer` outside the target width still comes back as the
+/// `RangeError` magnus raises for it.
+pub(crate) struct Whole<T>(pub(crate) T);
+
+impl<T: TryConvert> TryConvert for Whole<T> {
+    fn try_convert(value: Value) -> Result<Self, Error> {
+        if Integer::from_value(value).is_none() {
+            return Err(not_whole(value));
+        }
+        T::try_convert(value).map(Self)
+    }
+}
+
+fn not_whole(value: Value) -> Error {
+    let ruby = Ruby::get_with(value);
+    Error::new(
+        ruby.exception_type_error(),
+        format!(
+            "no implicit conversion of {} into Integer: {}",
+            value.class(),
+            value.inspect()
+        ),
+    )
+}
+
+/// The one required keyword of a constructor.
+pub(crate) fn required_kwarg<T: TryConvert>(keywords: RHash, name: &str) -> Result<T, Error> {
+    Ok(get_kwargs::<_, (T,), (), ()>(keywords, &[name], &[])?
+        .required
+        .0)
+}
+
+/// A keyword with a default the caller may leave out.
+pub(crate) fn optional_kwarg<T: TryConvert>(
+    keywords: RHash,
+    name: &str,
+) -> Result<Option<T>, Error> {
+    Ok(
+        get_kwargs::<_, (), (Option<T>,), ()>(keywords, &[], &[name])?
+            .optional
+            .0,
+    )
+}
+
+/// The shape a blob was written at, read from its core frame.
+pub(crate) fn blob_shape(ruby: &Ruby, blob: &[u8]) -> Result<usize, Error> {
+    let Some(field) = blob.get(SHAPE) else {
+        return Err(codec_error(ruby, CodecError::Truncated));
+    };
+    Ok(usize::from(u16::from_le_bytes([field[0], field[1]])))
+}
+
+/// The replica id a clock's blob carries after its core frame.
+pub(crate) fn trailing_replica(
+    ruby: &Ruby,
+    blob: &[u8],
+    frame_len: usize,
+) -> Result<ReplicaId, Error> {
+    let Some((field, _)) = blob
+        .get(frame_len..)
+        .and_then(<[u8]>::split_first_chunk::<FIELD_LEN>)
+    else {
+        return Err(codec_error(ruby, CodecError::Truncated));
+    };
+    Ok(u64::from_le_bytes(*field))
+}
+
+pub(crate) fn unsupported(ruby: &Ruby, name: &str, given: usize, supported: &[usize]) -> Error {
+    Error::new(
+        ruby.exception_arg_error(),
+        format!("{name} {given} is not supported, expected one of {supported:?}"),
+    )
+}
+
+pub(crate) fn unsupported_blob(ruby: &Ruby, name: &str, supported: &[usize]) -> Error {
+    Error::new(
+        ruby.exception_arg_error(),
+        format!("blob was written with a {name} outside {supported:?}"),
+    )
+}
+
+pub(crate) fn codec_error(ruby: &Ruby, error: CodecError) -> Error {
+    Error::new(ruby.exception_arg_error(), format!("codec: {error}"))
+}
+
+pub(crate) fn mismatch(ruby: &Ruby, name: &str) -> Error {
+    Error::new(
+        ruby.exception_arg_error(),
+        format!("the other {name} has a different shape"),
+    )
+}
+
+pub(crate) fn uninitialised(ruby: &Ruby) -> Error {
+    Error::new(
+        ruby.exception_runtime_error(),
+        "the merge_machines extension is not initialised",
+    )
+}
+
+pub(crate) fn defined_twice(ruby: &Ruby, name: &str) -> Error {
+    Error::new(
+        ruby.exception_runtime_error(),
+        format!("MergeMachines::{name} was initialised twice"),
+    )
+}
+
+/// Raises `MergeMachines::Full` for a state that ran out of slots.
+pub(crate) fn capacity(ruby: &Ruby, outcome: Result<(), CapacityError>) -> Result<(), Error> {
+    outcome.map_err(|error| raised(ruby, &FULL, error.to_string()))
+}
+
+/// Raises `MergeMachines::Exhausted` for a clock that ran out of timestamps.
+pub(crate) fn exhausted<T>(ruby: &Ruby, outcome: Result<T, ClockExhausted>) -> Result<T, Error> {
+    outcome.map_err(|error| raised(ruby, &EXHAUSTED, error.to_string()))
+}
+
+/// Raises `MergeMachines::Exhausted` for a set that ran out of tags.
+pub(crate) fn tags_exhausted(ruby: &Ruby) -> Error {
+    raised(ruby, &EXHAUSTED, "no tag left".to_owned())
+}
+
+fn raised(ruby: &Ruby, class: &OnceLock<Opaque<ExceptionClass>>, message: String) -> Error {
+    class.get().map_or_else(
+        || uninitialised(ruby),
+        |class| Error::new(ruby.get_inner(*class), message),
+    )
+}
+
+fn define_errors(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let base = module.define_error("Error", ruby.exception_standard_error())?;
+    let full = module.define_error("Full", base)?;
+    FULL.set(full.into())
+        .map_err(|_| defined_twice(ruby, "Full"))?;
+    let exhausted = module.define_error("Exhausted", base)?;
+    EXHAUSTED
+        .set(exhausted.into())
+        .map_err(|_| defined_twice(ruby, "Exhausted"))
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("MergeMachines")?;
+    module.const_set("NS_PER_SECOND", NS_PER_SECOND)?;
+    define_errors(ruby, module)?;
+    wall::define(ruby)?;
+    data::define(ruby, module)?;
+    logical::define(ruby, module)?;
+    hybrid::define(ruby, module)?;
+    gcounter::define(ruby, module)?;
+    pncounter::define(ruby, module)?;
+    lww::define(ruby, module)?;
+    gset::define(ruby, module)?;
+    orset::define(ruby, module)
+}