snapshot_machines 0.1.5-arm64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e5e8e2da13567b7ed203a812fb83148cb0cba953bea6897ed0222747d7ef4e8c
+  data.tar.gz: 85300d20edaf3d2660233d5dc6e3c9feb1cf287c0729f5330e317faf46eee815
+SHA512:
+  metadata.gz: 69d3c5cce99a493ffea4013c63108c13f32699e52172569b504f6cb1e82c216956d4810a4977bf2c6e9c1cf5d41809db05c73e7240e5873d5a0b9718044669d1
+  data.tar.gz: f5580d4e7e6d5d179e29809f4119eeee754a68480b5be9a133b73f7daa020f3506bd62b18a81640c18eb945c3549f249a4b84a3ecbb5863a78b45c0f15ba7384

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/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/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/extconf.rb

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

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,62 @@
+--- !ruby/object:Gem::Specification
+name: snapshot_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: arm64-darwin
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-06 00:00:00.000000000 Z
+dependencies: []
+description: An allocation-free Rust manifest model with a thin Ruby bridge. No snapshot
+  bytes or durable storage.
+email:
+- oss@seuros.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/snapshot_machines_native/core/CHANGELOG.md
+- ext/snapshot_machines_native/core/README.md
+- ext/snapshot_machines_native/extconf.rb
+- lib/snapshot_machines.rb
+- lib/snapshot_machines/version.rb
+- lib/snapshot_machines_native/snapshot_machines_native.bundle
+- 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
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Bounded native snapshot manifest planning for Ruby
+test_files: []