snapshot_machines 0.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 621669a04a2ca7d77dc8616a530150a8f57f9de1a3aee58f905e136838013436
+  data.tar.gz: 7b1c699b88f1f1b1e670e43617b6786c29707b06abed063ae546495dae38624f
+SHA512:
+  metadata.gz: 2b41ad11cd2efe310af8476a009554398aed6a47decba23300c5a7d17538a31ee5b09df01ed43ea6b8023736b366a1e8818c8b5974fefcff62fc872a7e5690b7
+  data.tar.gz: 907cdae62c69da019daf4c5d4270b2dce0aacbc1be467785485cda06fce11a7476ad7afa6accb26b62f71dd17b7d9f02613313ac9ba7eed0c588568e07970537

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [0.1.5](https://github.com/seuros/snapshot_machines/compare/snapshot_machines/v0.1.4...snapshot_machines/v0.1.5) (2026-11-06)
+
+
+### Bug Fixes
+
+* extract catalog ownership check for commit/abort ([f501351](https://github.com/seuros/snapshot_machines/commit/f5013515b918dfb5627939ae2d06b191298b5a85))
+
+## [0.1.4](https://github.com/seuros/snapshot_machines/compare/snapshot_machines/v0.1.3...snapshot_machines/v0.1.4) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([f544853](https://github.com/seuros/snapshot_machines/commit/f544853222f20d5e56b58199641258a676455f61))
+
+## [0.1.3](https://github.com/seuros/snapshot_machines/compare/snapshot_machines/v0.1.2...snapshot_machines/v0.1.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([002251a](https://github.com/seuros/snapshot_machines/commit/002251a711dd02f261ed4be6f255238fae2ef3ed))
+
+## [0.1.2](https://github.com/seuros/snapshot_machines/compare/snapshot_machines/v0.1.1...snapshot_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* cross builds no longer compile for the host ([e771bd5](https://github.com/seuros/snapshot_machines/commit/e771bd5f973692eef8035958143e29dc442237e7))
+
+## [0.1.1](https://github.com/seuros/snapshot_machines/compare/snapshot_machines-v0.1.0...snapshot_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([691a57e](https://github.com/seuros/snapshot_machines/commit/691a57e297015cf920bd3afc3ac9309c959c3af6))

data/Cargo.toml

@@ -0,0 +1,22 @@
+[workspace]
+members = ["ext/snapshot_machines_native/core", "ext/snapshot_machines_native/ffi"]
+default-members = ["ext/snapshot_machines_native/core"]
+resolver = "3"
+[workspace.package]
+edition = "2024"
+rust-version = "1.99"
+license = "MIT"
+[workspace.dependencies]
+snapshot-machines = { path = "ext/snapshot_machines_native/core" }
+magnus = { version = "0.9.3", default-features = false }
+rb-sys = { version = "0.9.130", default-features = false, features = ["stable-api-compiled-fallback"] }
+[workspace.lints.rust]
+unsafe_code = "deny"
+unused_must_use = "warn"
+missing_docs = "warn"
+[workspace.lints.clippy]
+all = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+nursery = { level = "warn", priority = -1 }
+unwrap_used = "deny"
+expect_used = "deny"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,218 @@
+# SnapshotMachines
+
+> Every incremental backup is a promise that the full one still exists. 🗃️
+
+A manifest catalog for Ruby. You tell it when a full snapshot starts and when it lands, and when each incremental one is taken on top. It remembers the chain, refuses to let you build on anything but the latest, keeps the old chain intact until a new full one has actually committed, and answers the only question that matters at 3 AM: to restore *this*, which manifests do I need, and in what order?
+
+## Quick Start
+
+```bash
+gem 'snapshot_machines'
+```
+
+```ruby
+catalog = SnapshotMachines::Catalog.new
+
+full = catalog.begin(nil)                      # nil means "start a full snapshot"
+catalog.commit(full, checksum_of(sunday_dump)) # => [1, nil, checksum]
+
+monday = catalog.begin(1)                      # build on manifest 1
+catalog.commit(monday, checksum_of(monday_delta)) # => [2, 1, checksum]
+
+catalog.restore_plan(2)
+# => [[1, nil, sunday_checksum], [2, 1, monday_checksum]]
+```
+
+Each manifest is a three-element array: its id, the id it builds on, and the checksum you gave it. The restore plan is the list of manifests to replay, oldest first.
+
+## A Message to the Resistance
+
+So you set up backups. Full dump every Sunday, incrementals Monday through Saturday, uploaded to a bucket with a lifecycle rule. Thirty days retention. Very responsible.
+
+Then a Wednesday restore fails. The incrementals from Monday and Tuesday are right there. Wednesday's is there. Sunday's full dump expired at midnight because it was thirty-one days old, and nobody told the lifecycle rule that three other files depend on it.
+
+The bytes were never the problem. The problem is that nothing in your system knew that Wednesday *needs* Sunday. The dependency lived in a naming convention and a vague memory of how the cron job works.
+
+This gem holds that dependency. It won't take the bytes, won't upload anything, won't verify a checksum. It keeps the chain of who-builds-on-whom, and it makes a full replacement wait until the replacement has actually landed, so the old chain is never orphaned by an optimistic cleanup.
+
+## Chapter 1: Stardate 2025.186, the AMS Chandy
+
+> **AMS Chandy**, NCC-4218, *Chandy*-class archive tender.
+> Keep the full captain's log, then know exactly which later pages depend on it.
+
+The tender doesn't carry the logs. It carries the index: this page is a complete log, these pages are amendments, each amendment names the page it amends. When a new complete log is being written, the old one stays on the shelf until the new one is bound. When the new one is bound, the old chain and all its amendments are struck from the index together.
+
+An ensign with a disk-space alert suggests:
+
+```ruby
+def prune_backups
+  Dir["backups/*.dump"].each do |file|
+    File.delete(file) if File.mtime(file) < 30.days.ago
+  end
+end
+```
+
+"That," says the archivist, "is how Wednesday becomes unrestorable."
+
+## The Flight Plan
+
+```mermaid
+stateDiagram-v2
+    [*] --> empty
+    empty --> pending_full: begin(nil)
+    pending_full --> chained: commit, manifest 1 is the new base
+    pending_full --> empty: abort, nothing recorded
+    chained --> pending_incremental: begin(latest id)
+    pending_incremental --> chained: commit, chain grows by one
+    pending_incremental --> chained: abort, chain unchanged
+    chained --> pending_replacement: begin(nil)
+    pending_replacement --> chained: commit, old chain discarded
+    pending_replacement --> chained: abort, old chain kept
+```
+
+And the week the full dump was replaced:
+
+```mermaid
+sequenceDiagram
+    participant Cron
+    participant Catalog
+    participant Bucket
+
+    Cron->>Catalog: begin(nil)
+    Catalog-->>Cron: pending 1
+    Cron->>Bucket: upload sunday.dump
+    Cron->>Catalog: commit(pending 1, checksum)
+    Catalog-->>Cron: [1, nil, checksum]
+
+    Cron->>Catalog: begin(1)
+    Catalog-->>Cron: pending 2
+    Cron->>Bucket: upload monday.delta
+    Cron->>Catalog: commit(pending 2, checksum)
+    Catalog-->>Cron: [2, 1, checksum]
+
+    Note over Cron: next Sunday
+    Cron->>Catalog: begin(nil)
+    Catalog-->>Cron: pending 3
+    Cron->>Bucket: upload sunday2.dump
+    Note over Bucket: upload fails halfway
+    Cron->>Catalog: abort(pending 3)
+    Catalog-->>Cron: true
+    Cron->>Catalog: restore_plan(2)
+    Catalog-->>Cron: [[1, nil, ..], [2, 1, ..]]
+    Note over Catalog: old chain untouched. Monday is still restorable.
+```
+
+## How the Catalog Works
+
+### A full snapshot
+
+Pass `nil` to `begin` and you get a `Pending` handle. Nothing is recorded yet. Record it with `commit` and the checksum you computed.
+
+```ruby
+catalog = SnapshotMachines::Catalog.new
+catalog.latest           # => nil, nothing yet
+
+pending = catalog.begin(nil)
+pending.id               # => 1
+catalog.commit(pending, 42)   # => [1, nil, 42]
+catalog.latest                # => [1, nil, 42]
+```
+
+A full manifest has `nil` as its base. It depends on nothing.
+
+### An incremental snapshot
+
+Pass the id of the latest manifest and the new one builds on it.
+
+```ruby
+monday = catalog.begin(1)
+catalog.commit(monday, 43)    # => [2, 1, 43]
+
+tuesday = catalog.begin(2)
+catalog.commit(tuesday, 44)   # => [3, 2, 44]
+```
+
+Only the latest manifest can be built on. Ask to build on 1 now and the answer is `nil`. The chain is a line, not a tree.
+
+```ruby
+catalog.begin(1)     # => nil, manifest 1 is no longer the tip
+catalog.begin(999)   # => nil, never heard of it
+```
+
+### Restore
+
+`restore_plan` walks back from the manifest you name to the full one it rests on, and hands you the list oldest first.
+
+```ruby
+catalog.restore_plan(3)
+# => [[1, nil, 42], [2, 1, 43], [3, 2, 44]]
+
+catalog.restore_plan(2)
+# => [[1, nil, 42], [2, 1, 43]]
+```
+
+Replay them in that order and you're at Tuesday.
+
+### Replacing the full snapshot
+
+A new full snapshot starts the same way, with `begin(nil)`. Until it commits, the old chain is exactly where it was.
+
+```ruby
+replacement = catalog.begin(nil)
+catalog.restore_plan(3)       # => still [[1, nil, 42], [2, 1, 43], [3, 2, 44]]
+
+catalog.commit(replacement, 50)   # => [4, nil, 50]
+catalog.restore_plan(3)           # => nil, that chain is gone
+catalog.restore_plan(4)           # => [[4, nil, 50]]
+```
+
+The moment the new full lands, every manifest of the old chain stops being restorable through this catalog. That's your signal that the old files can go. Not before.
+
+### Aborting
+
+Upload failed, disk filled up, someone hit Ctrl-C. Tell the catalog.
+
+```ruby
+attempt = catalog.begin(nil)
+catalog.abort(attempt)    # => true
+catalog.abort(attempt)    # => false, already dealt with
+catalog.latest            # => [4, nil, 50], unchanged
+```
+
+An aborted full attempt leaves the old chain alone. An aborted incremental leaves the chain one link shorter than it would have been. Nothing is ever half-recorded.
+
+### One at a time
+
+While a snapshot is pending, no other can begin. Commit it or abort it first.
+
+```ruby
+busy = catalog.begin(4)
+catalog.begin(nil)    # => nil
+catalog.begin(4)      # => nil
+catalog.abort(busy)   # => true
+```
+
+## The Rules of the Tender
+
+- **Checksums and ids are Integers** in `0..2**64-1`. The catalog stores the checksum; it never computes or verifies one. Floats and strings raise `TypeError`, negatives raise `RangeError`.
+- **A chain holds 32 links.** At capacity, `begin(latest)` returns `nil`. `begin(nil)` still works, so a new full snapshot is always possible.
+- **Handles belong to one catalog.** Hand a `Pending` from one catalog to another and you get `ArgumentError`. Commit the same handle twice and the second returns `nil`.
+- **Rejections return nil or false.** Only malformed input raises.
+- **Frozen means frozen.** `freeze` the catalog and `begin`, `commit`, and `abort` all raise `FrozenError`. Reads still work.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "The retention policy keeps thirty days of backups."
+### Reality: It keeps thirty days of files. Some of those files are useless alone.
+
+An incremental backup is not a backup. It's a diff. Its value is exactly zero without the full snapshot it was taken against, and a retention rule counting days has no idea which file that is. The catalog knows. Ask it before you delete anything.
+
+## What's Yours
+
+The catalog is the index, not the archive. Take the snapshot, compute the checksum, store the bytes somewhere durable, and only then `commit`. Persist the catalog's state alongside the bytes, because a catalog that lives only in memory forgets the chain with the process. When `restore_plan` says a manifest is gone, that's when the corresponding files are safe to remove.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: Sunday's dump was deleted on schedule. Wednesday's restore was not.**

data/ext/snapshot_machines_native/core/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.2.2](https://github.com/seuros/snapshot_machines/compare/snapshot-machines-v0.2.1...snapshot-machines-v0.2.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([f544853](https://github.com/seuros/snapshot_machines/commit/f544853222f20d5e56b58199641258a676455f61))
+
+## [0.2.1](https://github.com/seuros/snapshot_machines/compare/snapshot-machines-v0.2.0...snapshot-machines-v0.2.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([002251a](https://github.com/seuros/snapshot_machines/commit/002251a711dd02f261ed4be6f255238fae2ef3ed))
+
+## [0.2.0](https://github.com/seuros/snapshot_machines/compare/snapshot-machines-v0.1.0...snapshot-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([691a57e](https://github.com/seuros/snapshot_machines/commit/691a57e297015cf920bd3afc3ac9309c959c3af6))

data/ext/snapshot_machines_native/core/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "snapshot-machines"
+version = "0.2.2"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+description = "Bounded full/incremental checkpoint manifest lifecycle"
+readme = "README.md"
+exclude = ["src/**/tests.rs", "tests/"]
+keywords = ["snapshot", "checkpoint", "incremental", "backup", "no-std"]
+categories = ["no-std", "algorithms"]
+[lints]
+workspace = true

data/ext/snapshot_machines_native/core/README.md

@@ -0,0 +1,21 @@
+# snapshot-machines
+
+> **AMS Chandy**, NCC-4218, *Chandy*-class archive tender.
+
+Engine-room flight manual: chart checkpoint manifest ancestry, not snapshot bytes.
+
+Allocation-free `no_std` linear checkpoint manifest planning. Begin a full or
+incremental checkpoint, write/validate its data externally, then commit its
+manifest. Incrementals must name the latest committed checkpoint as parent.
+Aborted attempts consume IDs so stale completions cannot commit a replacement.
+
+A committed full checkpoint replaces the old manifest chain; a pending/aborted
+full checkpoint does not. Capacity exhaustion rejects incrementals and can be
+resolved by successfully committing a full checkpoint. Restore plans return
+the required full-to-target chain, not missing parent references.
+
+The supplied checksum is opaque metadata: this core does not calculate or verify
+it. There is no byte-diff engine, storage consistency boundary, serialization,
+data garbage collection, or crash recovery adapter. Persist manifests and data
+with a deployment-specific atomic publish protocol before deleting old data.
+IDs and pending handles are scoped to one catalog lifetime.

data/ext/snapshot_machines_native/core/src/lib.rs

@@ -0,0 +1,122 @@
+#![no_std]
+#![doc = include_str!("../README.md")]
+
+/// Catalog-scoped checkpoint identity.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct SnapshotId(pub u64);
+/// An in-progress checkpoint, issued by one catalog.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Pending {
+    id: SnapshotId,
+    base: Option<SnapshotId>,
+}
+impl Pending {
+    /// Identity for external data storage.
+    #[must_use]
+    pub const fn id(self) -> SnapshotId {
+        self.id
+    }
+}
+/// A committed full checkpoint or one incremental link.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Manifest {
+    /// Checkpoint identity.
+    pub id: SnapshotId,
+    /// Parent, or `None` for a full checkpoint.
+    pub base: Option<SnapshotId>,
+    /// Caller-computed data integrity metadata.
+    pub checksum: u64,
+}
+/// A bounded linear full-plus-incremental manifest chain.
+#[derive(Debug)]
+pub struct Catalog<const N: usize> {
+    manifests: [Option<Manifest>; N],
+    len: usize,
+    sequence: u64,
+    pending: Option<Pending>,
+}
+impl<const N: usize> Default for Catalog<N> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+impl<const N: usize> Catalog<N> {
+    /// Start an empty catalog in a fresh identity namespace.
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            manifests: [None; N],
+            len: 0,
+            sequence: 0,
+            pending: None,
+        }
+    }
+    /// Begin a full checkpoint, or an incremental of the latest committed one.
+    pub fn begin(&mut self, base: Option<SnapshotId>) -> Option<Pending> {
+        if N == 0 || self.pending.is_some() {
+            return None;
+        }
+        if let Some(base) = base
+            && (self.len == N || self.latest().map(|entry| entry.id) != Some(base))
+        {
+            return None;
+        }
+        let sequence = self.sequence.checked_add(1)?;
+        let pending = Pending {
+            id: SnapshotId(sequence),
+            base,
+        };
+        self.sequence = sequence;
+        self.pending = Some(pending);
+        Some(pending)
+    }
+    /// Publish a matching attempt after its data is durably written and verified.
+    pub fn commit(&mut self, pending: Pending, checksum: u64) -> Option<Manifest> {
+        if self.pending != Some(pending) {
+            return None;
+        }
+        let manifest = Manifest {
+            id: pending.id,
+            base: pending.base,
+            checksum,
+        };
+        if pending.base.is_none() {
+            self.manifests = [None; N];
+            self.len = 0;
+        }
+        self.manifests[self.len] = Some(manifest);
+        self.len += 1;
+        self.pending = None;
+        Some(manifest)
+    }
+    /// Abort without deleting committed manifests or reusing the attempt ID.
+    #[must_use]
+    pub fn abort(&mut self, pending: Pending) -> bool {
+        if self.pending != Some(pending) {
+            return false;
+        }
+        self.pending = None;
+        true
+    }
+    /// Latest committed checkpoint.
+    #[must_use]
+    pub const fn latest(&self) -> Option<Manifest> {
+        if self.len == 0 {
+            None
+        } else {
+            self.manifests[self.len - 1]
+        }
+    }
+    /// Copy a complete full-to-target restore chain; unused slots are `None`.
+    #[must_use]
+    pub fn restore_plan(&self, target: SnapshotId) -> Option<[Option<Manifest>; N]> {
+        let end = self.manifests[..self.len]
+            .iter()
+            .position(|entry| entry.is_some_and(|entry| entry.id == target))?;
+        let mut plan = [None; N];
+        plan[..=end].copy_from_slice(&self.manifests[..=end]);
+        Some(plan)
+    }
+}
+#[cfg(test)]
+mod tests;

data/ext/snapshot_machines_native/extconf.rb

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+require_relative 'ffi/extconf'

data/ext/snapshot_machines_native/ffi/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "snapshot_machines_native"
+version = "0.1.3"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+test = false
+doctest = false
+
+[dependencies]
+snapshot-machines.workspace = true
+magnus.workspace = true
+rb-sys.workspace = true
+
+[lints]
+workspace = true

data/ext/snapshot_machines_native/ffi/extconf.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+require 'mkmf'
+require 'pathname'
+require 'rb_sys/mkmf'
+create_rust_makefile('snapshot_machines_native/snapshot_machines_native') do |extension|
+  extension.ext_dir = Pathname(__dir__).relative_path_from(Pathname(Dir.pwd)).to_s
+  extension.profile = ENV.fetch('RB_SYS_CARGO_PROFILE', :release).to_sym
+end
+makefile = File.join(Dir.pwd, 'Makefile')
+File.write(makefile, File.read(makefile).gsub(
+  /^RB_SYS_CARGO_MANIFEST_DIR \?=.*$/,
+  "RB_SYS_CARGO_MANIFEST_DIR ?= #{File.expand_path(__dir__)}"
+))

data/ext/snapshot_machines_native/ffi/src/init.rs

@@ -0,0 +1,19 @@
+//! Private initialization boundary.
+use magnus::{Error, Ruby, function, method, prelude::*};
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("SnapshotMachines")?;
+    let pending = module.define_class("Pending", ruby.class_object())?;
+    pending.undef_default_alloc_func();
+    pending.define_method("id", method!(crate::Attempt::id, 0))?;
+    let class = module.define_class("Catalog", ruby.class_object())?;
+    class.undef_default_alloc_func();
+    class.define_singleton_method("new", function!(crate::Wrapper::new, 0))?;
+    class.define_method("capacity", method!(crate::Wrapper::capacity, 0))?;
+    class.define_method("begin", method!(crate::Wrapper::begin, 1))?;
+    class.define_method("commit", method!(crate::Wrapper::commit, 2))?;
+    class.define_method("abort", method!(crate::Wrapper::abort, 1))?;
+    class.define_method("latest", method!(crate::Wrapper::latest, 0))?;
+    class.define_method("restore_plan", method!(crate::Wrapper::restore_plan, 1))
+}

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

@@ -0,0 +1,109 @@
+//! Thin bindings for bounded manifest planning, never snapshot bytes.
+mod init;
+
+use magnus::{Error, Integer, RArray, Ruby, TryConvert, Value, prelude::*, typed_data::Obj};
+use snapshot_machines::{Catalog, Manifest, Pending, SnapshotId};
+use std::{cell::RefCell, sync::Arc};
+
+const CAPACITY: usize = 32;
+
+#[derive(Clone, Copy)]
+struct Id(u64);
+impl TryConvert for Id {
+    fn try_convert(value: Value) -> Result<Self, Error> {
+        if Integer::from_value(value).is_none() {
+            return Err(Error::new(
+                Ruby::get_with(value).exception_type_error(),
+                "expected an Integer",
+            ));
+        }
+        u64::try_convert(value).map(Self)
+    }
+}
+
+#[magnus::wrap(class = "SnapshotMachines::Pending", free_immediately, size)]
+struct Attempt {
+    owner: Arc<()>,
+    pending: Pending,
+}
+impl Attempt {
+    const fn id(&self) -> u64 {
+        self.pending.id().0
+    }
+}
+
+#[magnus::wrap(class = "SnapshotMachines::Catalog", free_immediately, size)]
+struct Wrapper {
+    owner: Arc<()>,
+    catalog: RefCell<Catalog<CAPACITY>>,
+}
+
+fn manifest(entry: Manifest) -> (u64, Option<u64>, u64) {
+    (entry.id.0, entry.base.map(|id| id.0), entry.checksum)
+}
+
+impl Wrapper {
+    fn new() -> Self {
+        Self {
+            owner: Arc::new(()),
+            catalog: RefCell::new(Catalog::new()),
+        }
+    }
+    #[allow(clippy::unused_self)] // Ruby instance query exposes the fixed bridge bound.
+    const fn capacity(&self) -> usize {
+        CAPACITY
+    }
+    /// Rejects a pending handle that some other catalog issued.
+    fn owns(&self, ruby: &Ruby, attempt: &Attempt) -> Result<(), Error> {
+        if Arc::ptr_eq(&self.owner, &attempt.owner) {
+            Ok(())
+        } else {
+            Err(Error::new(
+                ruby.exception_arg_error(),
+                "pending handle belongs to another catalog",
+            ))
+        }
+    }
+    fn begin(rb_self: Obj<Self>, base: Option<Id>) -> Result<Option<Attempt>, Error> {
+        rb_self.check_frozen()?;
+        let pending = rb_self
+            .catalog
+            .borrow_mut()
+            .begin(base.map(|id| SnapshotId(id.0)));
+        Ok(pending.map(|pending| Attempt {
+            owner: Arc::clone(&rb_self.owner),
+            pending,
+        }))
+    }
+    fn commit(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        attempt: &Attempt,
+        checksum: Id,
+    ) -> Result<Option<(u64, Option<u64>, u64)>, Error> {
+        rb_self.check_frozen()?;
+        rb_self.owns(ruby, attempt)?;
+        let result = rb_self
+            .catalog
+            .borrow_mut()
+            .commit(attempt.pending, checksum.0);
+        Ok(result.map(manifest))
+    }
+    fn abort(ruby: &Ruby, rb_self: Obj<Self>, attempt: &Attempt) -> Result<bool, Error> {
+        rb_self.check_frozen()?;
+        rb_self.owns(ruby, attempt)?;
+        Ok(rb_self.catalog.borrow_mut().abort(attempt.pending))
+    }
+    fn latest(&self) -> Option<(u64, Option<u64>, u64)> {
+        self.catalog.borrow().latest().map(manifest)
+    }
+    fn restore_plan(ruby: &Ruby, rb_self: &Self, target: Id) -> Result<Option<RArray>, Error> {
+        let plan = rb_self.catalog.borrow().restore_plan(SnapshotId(target.0));
+        let Some(plan) = plan else { return Ok(None) };
+        let result = ruby.ary_new();
+        for entry in plan.into_iter().flatten() {
+            result.push(manifest(entry))?;
+        }
+        Ok(Some(result))
+    }
+}

data/lib/snapshot_machines/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module SnapshotMachines
+  VERSION = '0.1.5'
+end

data/lib/snapshot_machines.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+require_relative 'snapshot_machines/version'
+require 'snapshot_machines_native/snapshot_machines_native'

data/sig/snapshot_machines.rbs

@@ -0,0 +1,15 @@
+module SnapshotMachines
+  VERSION: String
+  class Pending
+    def id: () -> Integer
+  end
+  class Catalog
+    def self.new: () -> Catalog
+    def capacity: () -> Integer
+    def begin: (Integer?) -> Pending?
+    def commit: (Pending, Integer) -> [Integer, Integer?, Integer]?
+    def abort: (Pending) -> bool
+    def latest: () -> [Integer, Integer?, Integer]?
+    def restore_plan: (Integer) -> Array[[Integer, Integer?, Integer]]?
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: snapshot_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: ruby
+authors:
+- Abdelkader Boudih
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+description: An allocation-free Rust manifest model with a thin Ruby bridge. No snapshot
+  bytes or durable storage.
+email:
+- oss@seuros.com
+executables: []
+extensions:
+- ext/snapshot_machines_native/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.toml
+- LICENSE.txt
+- README.md
+- ext/snapshot_machines_native/core/CHANGELOG.md
+- ext/snapshot_machines_native/core/Cargo.toml
+- ext/snapshot_machines_native/core/README.md
+- ext/snapshot_machines_native/core/src/lib.rs
+- ext/snapshot_machines_native/extconf.rb
+- ext/snapshot_machines_native/ffi/Cargo.toml
+- ext/snapshot_machines_native/ffi/extconf.rb
+- ext/snapshot_machines_native/ffi/src/init.rs
+- ext/snapshot_machines_native/ffi/src/lib.rs
+- lib/snapshot_machines.rb
+- lib/snapshot_machines/version.rb
+- sig/snapshot_machines.rbs
+homepage: https://github.com/seuros/snapshot_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/snapshot_machines
+  bug_tracker_uri: https://github.com/seuros/snapshot_machines/issues
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: snapshot_machines_native
+  cargo_manifest_path: ext/snapshot_machines_native/ffi/Cargo.toml
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Bounded native snapshot manifest planning for Ruby
+test_files: []