mechanomeld 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc3b7a58de04a5445e59c398a68556fddb11bd3ec013451733e9a962e6121608
-  data.tar.gz: 29c2f1e1c0eb082b0416994131c78073e3a93c8ffdbe122e3af96887e3712bb2
+  metadata.gz: 17ff6a2f602dc4e7a849a437f26c3d67194da8508f17b093bb8b807b9832ad5e
+  data.tar.gz: 45cb8059e7b6f004f4ae95db489cd203b1d97ba35840ae559a7185c8e493ca5c
 SHA512:
-  metadata.gz: 16f9c6cd1505ce2931ac90f75ac9eb391eea8a2c7be2d7e6e6fcb513819e4c2eebfa849ce02cbcd96c8b833caab3d73d5eeb151e6087739d47aee5ab9e14c6aa
-  data.tar.gz: 3d0c3dbbbd11ae5733fcb260548c2aa2eb03ce399970eacffc8571fa111e014e6471618737704914c2162def47ec4c204b3ec4f62158ad1581751e86ad525f07
+  metadata.gz: 7e7b6c9ad63929ec97f7513fd556d8a8860de99530fd67db5055bc169543dc9ae297a5998c325e9bee3f40a0d20eb4f92310fabf2b072e0c8b4a1723a5e35bbe
+  data.tar.gz: d8a0eb87b94e31175ce1e409e6535a33825bd3789f4c4233706f9eed0e5a34ddefa52813aa1053e00af80f087161f58f30fe2f453f58cc1c4faab957ae54d649

data/CHANGELOG.md

@@ -5,17 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## [0.1.0] - 2026-09-17
+## [0.1.2] - 2026-09-28
 
 ### Added
 
-- Initial release
-- Mechanomeld::Counter, Timestamp, Uint, Bytes, and Text value classes (6df6951)
-- Mechanomeld::Document.load reads documents saved by JavaScript Automerge (c7d31d8)
-- Document#get, #[], and #to_h read values by path (c7d31d8)
-- Document#keys and #length for maps, lists, and text (1d80c0b)
-- Mechanomeld::Document.new(actor_id:) creates an empty document (bccb69c)
-- Document#put, #[]=, #delete, and #save (bccb69c)
-- Document#commit(message:, timestamp:) and #rollback (a8ef491)
-- Document#change commits a block and rolls back if it raises (a8ef491)
-- Mechanomeld::Document.from builds a committed document from a Hash (a8ef491)
+- Document#diff(from_heads, to_heads = heads) returns Automerge's patches between two versions of a document, as Hashes (9c9bf6d)
+
+## [0.1.1] - 2026-09-25
+
+### Added
+
+- Document#load_incremental applies saved Automerge bytes into an existing document (d60a3eb)
+- Document.load_repo reads a document from automerge-repo's NodeFSStorageAdapter directory (d60a3eb)
+- Document#heads returns the document's change hashes as hex, matching JavaScript's Automerge.getHeads (d60a3eb)
+- Document#includes_heads?(heads) reports whether a document is at or past a set of heads (d60a3eb)
+- Mechanomeld::SyncState, the per-peer sync state, with encode and decode for persistence (eea3a51)
+- Document#generate_sync_message and #receive_sync_message, Automerge's per-document sync protocol (eea3a51)
+
+### Changed
+
+- releases also publish an x86_64-linux-musl platform gem (159dd59)

data/README.md

@@ -28,6 +28,78 @@ end
 File.binwrite("groceries.automerge", doc.save)
 ```
 
+### Documents stored by automerge-repo
+
+`Document.load_repo` reads a document straight out of the directory written by `@automerge/automerge-repo`'s `NodeFSStorageAdapter`, applying its snapshot and incremental chunks and skipping its sync-state files.
+
+```ruby
+doc = Mechanomeld::Document.load_repo("automerge-repo-data", "4NtRZtd6yUtzf8qmEpKitAaW4JRp")
+```
+
+`Document#load_incremental(bytes)` is the piece underneath: it applies any saved Automerge bytes (a full save, a snapshot chunk, or an incremental change chunk) into an existing document and returns the document.
+
+### Heads
+
+`Document#heads` is the document's version: the change hashes JavaScript's `Automerge.getHeads(doc)` returns, as lowercase hex, so the two sides compare with `==`. `Document#includes_heads?(heads)` is true when every hash in `heads` is a change the document already contains, so `heads` is the same version or an older one.
+
+```ruby
+doc.heads                  # => ["9d434616e7af865757bad75cdebe4151bccf7e29214a71f2a65150846c2a4275"]
+doc.includes_heads?(heads) # => true when the document is at or past `heads`
+```
+
+Both take hex. automerge-repo's `handle.heads()` returns base58 URL heads, which are not accepted; send `Automerge.getHeads(handle.doc())` from JavaScript instead. A hash that is not 32 bytes of hex raises `Mechanomeld::Error`; a well-formed hash the document does not have is simply not included. Like `save`, both commit any pending change first.
+
+### What changed between two versions
+
+`Document#diff(from_heads, to_heads = doc.heads)` is Automerge's diff: the patches that take the document from one version to another, as Hashes with String keys. Both arguments are hex heads as `Document#heads` returns them; `to_heads` defaults to the current heads, and `[]` as `from_heads` diffs from the empty document.
+
+```ruby
+before = doc.heads
+doc.change { |d| d[["scores", "bravo"]] = 7 }
+doc.diff(before)
+# => [{"action" => "put", "path" => ["scores", "bravo"], "value" => 7, "conflict" => false}]
+```
+
+Every patch has `"action"` and `"path"`. The path addresses the property the patch touches from the root, map keys as Strings and list indexes as Integers, as JavaScript's `Automerge.diff` reports it. The other keys depend on the action:
+
+| action | keys |
+|---|---|
+| `put` | `value`, `conflict` (true when this value won a concurrent write) |
+| `delete` | `index` and `length` when deleting from a list; nothing more for a map key |
+| `insert` | `values`, the elements inserted at `path`'s index, in order |
+| `splice_text` | `value`, the String spliced into a `Text` at `path`'s index |
+| `increment` | `value`, the amount a `Counter` changed by, which may be negative |
+| `conflict` | nothing more: a concurrent write now conflicts at `path` |
+| `mark` | `marks`, each `{"name", "value", "start", "end"}` on a `Text` |
+
+Putting or inserting a map, list, or `Text` yields the empty container (`{}`, `[]`, or `Mechanomeld::Text.new("")`); its contents follow as their own patches. Values use the same Ruby types as `get`. A head that is not hex, or that names a change the document does not contain, raises `Mechanomeld::Error`. Like `save`, `diff` commits any pending change first.
+
+### Syncing with a peer
+
+`Document#generate_sync_message` and `Document#receive_sync_message` run Automerge's per-document sync protocol, so a Ruby document can exchange just the changes each side lacks with another Automerge peer: JavaScript's `Automerge.generateSyncMessage` / `receiveSyncMessage`, or another Ruby document. A `Mechanomeld::SyncState` tracks what one peer is known to have; keep one per peer for each document.
+
+```ruby
+left = Mechanomeld::Document.load(bytes)
+right = Mechanomeld::Document.load(bytes)
+left.change { |d| d["left"] = 1 }
+right.change { |d| d["right"] = 2 }
+
+left_state = Mechanomeld::SyncState.new  # left's view of right
+right_state = Mechanomeld::SyncState.new # right's view of left
+loop do
+  to_right = left.generate_sync_message(left_state)
+  right.receive_sync_message(right_state, to_right) if to_right
+  to_left = right.generate_sync_message(right_state)
+  left.receive_sync_message(left_state, to_left) if to_left
+  break if to_right.nil? && to_left.nil?
+end
+left.heads == right.heads # => true
+```
+
+Messages are binary Strings. `generate_sync_message` returns nil when the peer is up to date or the last message is still unanswered. `SyncState#encode` and `SyncState.decode(bytes)` carry a state across connections, keeping only the heads both sides are known to share (as JavaScript's `encodeSyncState` does), so a process that handles one message per request can decode, receive, generate, and encode again. Like `save`, both sync methods commit any pending change first. Bytes that are not a sync message or a sync state raise `Mechanomeld::Error`. The protocol carries no document identity: a message from a peer holding a different document merges that document in.
+
+This is the per-document protocol only. An automerge-repo sync server wraps these messages in its own envelope (peer and document ids, join and leave messages, CBOR encoding), which this gem does not provide.
+
 ### Values
 
 | Automerge | Ruby |
@@ -54,7 +126,7 @@ mise install
 mise run setup         # bundle install, npm ci for fixtures
 mise run test          # compile the extension and run the tests
 mise run test:interop  # check JavaScript reads Ruby-written documents
-mise run fixtures      # regenerate test/fixtures/*.automerge
+mise run fixtures      # regenerate test/fixtures/*.automerge, heads.json, and repo/
 ```
 
 Check packaging with `gem build mechanomeld.gemspec`. Do not run `rake build` or `rake release` locally: reissue bumps the version and commits during `build`.

data/ext/mechanomeld/src/diff.rs

@@ -0,0 +1,100 @@
+//! Converting automerge patches into Ruby hashes.
+//!
+//! Every patch becomes `{"action" => ..., "path" => [...]}` plus the fields that
+//! action carries. `path` addresses the property the patch touches from the root, as
+//! JavaScript's `Automerge.diff` reports it. A put or insert of a map, list, or text
+//! carries the empty container; the children arrive as their own patches.
+
+use automerge::{marks::Mark, ObjType, Patch, PatchAction, Prop, Value as AmValue};
+use magnus::{prelude::*, Error, RHash, Ruby, Value};
+
+use crate::classes::TEXT;
+use crate::errors::error;
+use crate::read;
+
+pub fn patch(ruby: &Ruby, patch: &Patch) -> Result<RHash, Error> {
+    let (action, last) = match &patch.action {
+        PatchAction::PutMap { key, .. } => ("put", Some(Prop::Map(key.clone()))),
+        PatchAction::PutSeq { index, .. } => ("put", Some(Prop::Seq(*index))),
+        PatchAction::Insert { index, .. } => ("insert", Some(Prop::Seq(*index))),
+        PatchAction::SpliceText { index, .. } => ("splice_text", Some(Prop::Seq(*index))),
+        PatchAction::Increment { prop, .. } => ("increment", Some(prop.clone())),
+        PatchAction::Conflict { prop } => ("conflict", Some(prop.clone())),
+        PatchAction::DeleteMap { key } => ("delete", Some(Prop::Map(key.clone()))),
+        PatchAction::DeleteSeq { index, .. } => ("delete", Some(Prop::Seq(*index))),
+        PatchAction::Mark { .. } => ("mark", None),
+    };
+    let path = ruby.ary_new_capa(patch.path.len() + 1);
+    for (_, prop) in &patch.path {
+        path.push(prop_value(ruby, prop))?;
+    }
+    if let Some(prop) = &last {
+        path.push(prop_value(ruby, prop))?;
+    }
+    let hash = ruby.hash_new();
+    hash.aset("action", action)?;
+    hash.aset("path", path)?;
+    match &patch.action {
+        PatchAction::PutMap {
+            value, conflict, ..
+        }
+        | PatchAction::PutSeq {
+            value, conflict, ..
+        } => {
+            hash.aset("value", self::value(ruby, &value.0)?)?;
+            hash.aset("conflict", *conflict)?;
+        }
+        PatchAction::Insert { values, .. } => {
+            let array = ruby.ary_new_capa(values.len());
+            for (item, _, _) in values.iter() {
+                array.push(self::value(ruby, item)?)?;
+            }
+            hash.aset("values", array)?;
+        }
+        PatchAction::SpliceText { value, .. } => {
+            hash.aset("value", ruby.str_new(&value.make_string()))?;
+        }
+        PatchAction::Increment { value, .. } => {
+            hash.aset("value", *value)?;
+        }
+        PatchAction::DeleteSeq { index, length } => {
+            hash.aset("index", *index)?;
+            hash.aset("length", *length)?;
+        }
+        PatchAction::Mark { marks } => {
+            let array = ruby.ary_new_capa(marks.len());
+            for mark in marks {
+                array.push(self::mark(ruby, mark)?)?;
+            }
+            hash.aset("marks", array)?;
+        }
+        PatchAction::Conflict { .. } | PatchAction::DeleteMap { .. } => {}
+    }
+    Ok(hash)
+}
+
+fn prop_value(ruby: &Ruby, prop: &Prop) -> Value {
+    match prop {
+        Prop::Map(key) => ruby.str_new(key).as_value(),
+        Prop::Seq(index) => ruby.integer_from_u64(*index as u64).as_value(),
+    }
+}
+
+fn value(ruby: &Ruby, value: &AmValue<'_>) -> Result<Value, Error> {
+    match value {
+        AmValue::Scalar(scalar) => read::scalar(ruby, scalar),
+        AmValue::Object(ObjType::Map) => Ok(ruby.hash_new().as_value()),
+        AmValue::Object(ObjType::List) => Ok(ruby.ary_new().as_value()),
+        AmValue::Object(ObjType::Text) => read::wrap(ruby, &TEXT, ruby.str_new("")),
+        AmValue::Object(ObjType::Table) => Err(error(ruby, "Automerge tables are not supported")),
+    }
+}
+
+fn mark(ruby: &Ruby, mark: &Mark) -> Result<RHash, Error> {
+    let hash = ruby.hash_new();
+    hash.aset("name", mark.name.as_str())?;
+    hash.aset("value", read::scalar(ruby, &mark.value)?)?;
+    hash.aset("start", mark.start)?;
+    hash.aset("end", mark.end)?;
+    Ok(hash)
+}

data/ext/mechanomeld/src/document.rs

@@ -2,8 +2,9 @@ use std::cell::{Ref, RefCell, RefMut};
 use std::str::FromStr;
 
 use automerge::{
+    sync::{Message, SyncDoc},
     transaction::{CommitOptions, Transactable},
-    ActorId, AutoCommit, LoadOptions, ObjType, ReadDoc, TextEncoding, ROOT,
+    ActorId, AutoCommit, ChangeHash, LoadOptions, ObjType, ReadDoc, TextEncoding, ROOT,
 };
 use magnus::{
     prelude::*,
@@ -13,7 +14,8 @@ use magnus::{
 };
 
 use crate::errors::{arg_error, automerge_error, error};
-use crate::{path, read, write};
+use crate::sync_state::SyncState;
+use crate::{diff, path, read, write};
 
 /// Text indexes count Unicode code points, matching Ruby's `String#length`.
 const ENCODING: TextEncoding = TextEncoding::UnicodeCodePoint;
@@ -62,6 +64,21 @@ impl Document {
         })
     }
 
+    /// `doc.load_incremental(bytes)`: applies a full save, snapshot, or incremental
+    /// change chunk into this document.
+    pub fn load_incremental(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        bytes: RString,
+    ) -> Result<Obj<Self>, Error> {
+        let data = unsafe { bytes.as_slice() }.to_vec();
+        rb_self
+            .doc_mut(ruby)?
+            .load_incremental(&data)
+            .map_err(|e| error(ruby, format!("could not load Automerge document: {e}")))?;
+        Ok(rb_self)
+    }
+
     /// `doc.get(path)`: the value at `path`, or nil when anything along it is missing.
     pub fn get(ruby: &Ruby, rb_self: &Self, path: Value) -> Result<Value, Error> {
         let segments = path::segments(path)?;
@@ -168,6 +185,102 @@ impl Document {
         let bytes = rb_self.doc_mut(ruby)?.save();
         Ok(ruby.str_from_slice(&bytes))
     }
+
+    /// `doc.heads`: the current heads as lowercase hex change hashes, the format
+    /// JavaScript's `Automerge.getHeads` returns.
+    pub fn heads(ruby: &Ruby, rb_self: &Self) -> Result<RArray, Error> {
+        let heads = rb_self.doc_mut(ruby)?.get_heads();
+        Ok(ruby.ary_from_iter(heads.iter().map(ChangeHash::to_string)))
+    }
+
+    /// `doc.includes_heads?(heads)`: whether every hex change hash in `heads` is a
+    /// change this document already contains.
+    pub fn includes_heads(ruby: &Ruby, rb_self: &Self, heads: Vec<String>) -> Result<bool, Error> {
+        let hashes = heads
+            .iter()
+            .map(|hex| change_hash(ruby, hex))
+            .collect::<Result<Vec<_>, _>>()?;
+        let mut doc = rb_self.doc_mut(ruby)?;
+        Ok(hashes
+            .iter()
+            .all(|hash| doc.get_change_meta_by_hash(hash).is_some()))
+    }
+
+    /// `doc.diff(from_heads, to_heads = heads)`: the patches that take the document from
+    /// `from_heads` to `to_heads`, as Hashes (see diff.rs for their shape). `[]` as
+    /// `from_heads` diffs from the empty document. Every head must be a change this
+    /// document contains.
+    pub fn diff(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<RArray, Error> {
+        let args = scan_args::<(Vec<String>,), (Option<Vec<String>>,), (), (), (), ()>(args)?;
+        let mut doc = rb_self.doc_mut(ruby)?;
+        let from = known_heads(ruby, &mut doc, &args.required.0)?;
+        let to = match args.optional.0 {
+            Some(heads) => known_heads(ruby, &mut doc, &heads)?,
+            None => doc.get_heads(),
+        };
+        let patches = doc.diff(&from, &to);
+        let array = ruby.ary_new_capa(patches.len());
+        for patch in &patches {
+            array.push(diff::patch(ruby, patch)?)?;
+        }
+        Ok(array)
+    }
+
+    /// `doc.generate_sync_message(sync_state)`: the next binary message for the peer
+    /// `sync_state` tracks, or nil when there is nothing to send.
+    pub fn generate_sync_message(
+        ruby: &Ruby,
+        rb_self: &Self,
+        sync_state: &SyncState,
+    ) -> Result<Option<RString>, Error> {
+        let mut doc = rb_self.doc_mut(ruby)?;
+        let mut state = sync_state.state_mut(ruby)?;
+        let message = doc.sync().generate_sync_message(&mut state);
+        Ok(message.map(|message| ruby.str_from_slice(&message.encode())))
+    }
+
+    /// `doc.receive_sync_message(sync_state, bytes)`: applies a peer's message to this
+    /// document and to `sync_state`.
+    pub fn receive_sync_message(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        sync_state: &SyncState,
+        bytes: RString,
+    ) -> Result<Obj<Self>, Error> {
+        let data = unsafe { bytes.as_slice() }.to_vec();
+        let message = Message::decode(&data)
+            .map_err(|e| error(ruby, format!("could not decode sync message: {e}")))?;
+        {
+            let mut doc = rb_self.doc_mut(ruby)?;
+            let mut state = sync_state.state_mut(ruby)?;
+            doc.sync()
+                .receive_sync_message(&mut state, message)
+                .map_err(|e| automerge_error(ruby, e))?;
+        }
+        Ok(rb_self)
+    }
+}
+
+fn change_hash(ruby: &Ruby, hex: &str) -> Result<ChangeHash, Error> {
+    ChangeHash::from_str(hex).map_err(|e| error(ruby, format!("invalid change hash {hex:?}: {e}")))
+}
+
+/// Parses hex change hashes, rejecting any change `doc` does not contain.
+fn known_heads(
+    ruby: &Ruby,
+    doc: &mut AutoCommit,
+    heads: &[String],
+) -> Result<Vec<ChangeHash>, Error> {
+    heads
+        .iter()
+        .map(|hex| {
+            let hash = change_hash(ruby, hex)?;
+            if doc.get_change_meta_by_hash(&hash).is_none() {
+                return Err(error(ruby, format!("unknown change hash {hex:?}")));
+            }
+            Ok(hash)
+        })
+        .collect()
 }
 
 fn optional_path(ruby: &Ruby, args: &[Value]) -> Result<Vec<Value>, Error> {

data/ext/mechanomeld/src/lib.rs

@@ -1,13 +1,16 @@
 mod classes;
+mod diff;
 mod document;
 mod errors;
 mod path;
 mod read;
+mod sync_state;
 mod write;
 
 use magnus::{function, method, prelude::*, Error, Ruby};
 
 use crate::document::Document;
+use crate::sync_state::SyncState;
 
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
@@ -15,6 +18,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     let class = module.define_class("Document", ruby.class_object())?;
     class.define_singleton_method("new", function!(Document::new, -1))?;
     class.define_singleton_method("load", function!(Document::load, 1))?;
+    class.define_method("load_incremental", method!(Document::load_incremental, 1))?;
     class.define_method("get", method!(Document::get, 1))?;
     class.define_method("keys", method!(Document::keys, -1))?;
     class.define_method("length", method!(Document::length, -1))?;
@@ -23,5 +27,20 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     class.define_method("commit", method!(Document::commit, -1))?;
     class.define_method("rollback", method!(Document::rollback, 0))?;
     class.define_method("save", method!(Document::save, 0))?;
+    class.define_method("heads", method!(Document::heads, 0))?;
+    class.define_method("includes_heads?", method!(Document::includes_heads, 1))?;
+    class.define_method("diff", method!(Document::diff, -1))?;
+    class.define_method(
+        "generate_sync_message",
+        method!(Document::generate_sync_message, 1),
+    )?;
+    class.define_method(
+        "receive_sync_message",
+        method!(Document::receive_sync_message, 2),
+    )?;
+    let sync_state = module.define_class("SyncState", ruby.class_object())?;
+    sync_state.define_singleton_method("new", function!(SyncState::new, 0))?;
+    sync_state.define_singleton_method("decode", function!(SyncState::decode, 1))?;
+    sync_state.define_method("encode", method!(SyncState::encode, 0))?;
     Ok(())
 }

data/ext/mechanomeld/src/read.rs

@@ -72,7 +72,11 @@ pub fn scalar(ruby: &Ruby, scalar: &ScalarValue) -> Result<Value, Error> {
 }
 
 /// Builds a scalar wrapper by allocating it and setting `@value`, without running Ruby code.
-fn wrap(ruby: &Ruby, class: &'static Lazy<RClass>, value: impl IntoValue) -> Result<Value, Error> {
+pub fn wrap(
+    ruby: &Ruby,
+    class: &'static Lazy<RClass>,
+    value: impl IntoValue,
+) -> Result<Value, Error> {
     let instance = ruby.get_inner(class).obj_alloc()?;
     let object = RObject::try_convert(instance.as_value())?;
     object.ivar_set("@value", value)?;

data/ext/mechanomeld/src/sync_state.rs

@@ -0,0 +1,49 @@
+use std::cell::{Ref, RefCell, RefMut};
+
+use automerge::sync::State;
+use magnus::{Error, RString, Ruby};
+
+use crate::errors::error;
+
+/// What a document knows about one peer while syncing with it.
+#[magnus::wrap(class = "Mechanomeld::SyncState", free_immediately, size)]
+pub struct SyncState {
+    inner: RefCell<State>,
+}
+
+impl SyncState {
+    fn state(&self, ruby: &Ruby) -> Result<Ref<'_, State>, Error> {
+        self.inner
+            .try_borrow()
+            .map_err(|_| error(ruby, "sync state is being modified"))
+    }
+
+    pub fn state_mut(&self, ruby: &Ruby) -> Result<RefMut<'_, State>, Error> {
+        self.inner
+            .try_borrow_mut()
+            .map_err(|_| error(ruby, "sync state is already in use"))
+    }
+
+    /// `SyncState.new`: a fresh state for a peer this document has not synced with.
+    pub fn new() -> Self {
+        Self {
+            inner: RefCell::new(State::new()),
+        }
+    }
+
+    /// `SyncState.decode(bytes)`
+    pub fn decode(ruby: &Ruby, bytes: RString) -> Result<Self, Error> {
+        let data = unsafe { bytes.as_slice() }.to_vec();
+        let state = State::decode(&data)
+            .map_err(|e| error(ruby, format!("could not decode sync state: {e}")))?;
+        Ok(Self {
+            inner: RefCell::new(state),
+        })
+    }
+
+    /// `sync_state.encode`: the state as a binary String, keeping only what is worth
+    /// reusing on a later connection with the same peer.
+    pub fn encode(ruby: &Ruby, rb_self: &Self) -> Result<RString, Error> {
+        Ok(ruby.str_from_slice(&rb_self.state(ruby)?.encode()))
+    }
+}

data/lib/mechanomeld/document.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module Mechanomeld
-  # Native methods (new, load, get, keys, length, put, delete, commit, rollback, save)
-  # are defined in ext/mechanomeld/src/document.rs.
+  # Native methods (new, load, load_incremental, get, keys, length, put, delete, commit,
+  # rollback, save, heads, includes_heads?, diff, generate_sync_message,
+  # receive_sync_message) are defined in ext/mechanomeld/src/document.rs.
   class Document
     def self.from(hash, actor_id: nil)
       raise ArgumentError, "Automerge document root must be a Hash" unless hash.is_a?(Hash)
@@ -13,6 +14,19 @@ module Mechanomeld
       doc
     end
 
+    # Loads a document from the directory written by @automerge/automerge-repo's
+    # NodeFSStorageAdapter. Snapshot chunks are applied before incremental ones, as
+    # automerge-repo does; its sync-state files are not document data and are skipped.
+    def self.load_repo(base_dir, document_id)
+      document_dir = File.join(base_dir, document_id[0, 2], document_id[2..])
+      chunks = %w[snapshot incremental].flat_map do |kind|
+        Dir.glob(File.join(document_dir, kind, "*")).sort.select { |path| File.file?(path) }
+      end
+      raise Error, "no chunks for document #{document_id} in #{base_dir}" if chunks.empty?
+
+      chunks.each_with_object(new) { |path, doc| doc.load_incremental(File.binread(path)) }
+    end
+
     def [](path)
       get(path)
     end

data/lib/mechanomeld/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mechanomeld
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mechanomeld
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Jim Gay
@@ -41,11 +41,13 @@ files:
 - ext/mechanomeld/Cargo.toml
 - ext/mechanomeld/extconf.rb
 - ext/mechanomeld/src/classes.rs
+- ext/mechanomeld/src/diff.rs
 - ext/mechanomeld/src/document.rs
 - ext/mechanomeld/src/errors.rs
 - ext/mechanomeld/src/lib.rs
 - ext/mechanomeld/src/path.rs
 - ext/mechanomeld/src/read.rs
+- ext/mechanomeld/src/sync_state.rs
 - ext/mechanomeld/src/write.rs
 - lib/mechanomeld.rb
 - lib/mechanomeld/document.rb
@@ -74,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Read and write Automerge documents from Ruby
 test_files: []