saga_machines 0.1.5-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b1ae867a5bb8584ba3e03caa305889c6611c6338df228cfdf3d55140ce45490
+  data.tar.gz: 9c1495642d5e789e840abad8798076d280118c9c6c23b592b1573903773d994e
+SHA512:
+  metadata.gz: ab901036c5d9376e9d7e3de5a4bd0f17c4c5e3a95b89b7a7e110d0c952bc8879a0fbf3fc39c3c12c6f2631a0c8dc5c5c72ea7c4aacdc5c386d11b86c5a726223
+  data.tar.gz: 9b75c1080a3cdd39002ccaa5d17ca4fce06c37d9b1b77117e4c7b1a6ac0ad750ecfc8dbe11a0e30e0e2a36e8f2db58f1983aa4ed7dcb7aa46cba22dce783bbb8

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## [0.1.5](https://github.com/seuros/saga_machines/compare/saga_machines/v0.1.4...saga_machines/v0.1.5) (2026-11-06)
+
+
+### Bug Fixes
+
+* build against dedup-machines 0.3 ([fa36da9](https://github.com/seuros/saga_machines/commit/fa36da96c3aab595ff4daaa421a1f3e0d7c02fe9))
+* require dedup-machines 0.3 ([e192ae3](https://github.com/seuros/saga_machines/commit/e192ae3fb7c33882826dfc56c3582cd2e685e6a3))
+
+## [0.1.4](https://github.com/seuros/saga_machines/compare/saga_machines/v0.1.3...saga_machines/v0.1.4) (2026-11-06)
+
+
+### Features
+
+* restore a saga from persisted progress ([6c98ddd](https://github.com/seuros/saga_machines/commit/6c98ddd8fc44b880dc8bf195f8d5a8e32048b423))
+
+## [0.1.3](https://github.com/seuros/saga_machines/compare/saga_machines/v0.1.2...saga_machines/v0.1.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([660b649](https://github.com/seuros/saga_machines/commit/660b649c5b0229ab715571ecb0b97270dcaacfab))
+
+## [0.1.2](https://github.com/seuros/saga_machines/compare/saga_machines/v0.1.1...saga_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([38c7ba8](https://github.com/seuros/saga_machines/commit/38c7ba8523f9ad783b258df3df15e2e2b5f3b6a0))
+
+## [0.1.1](https://github.com/seuros/saga_machines/compare/saga_machines-v0.1.0...saga_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([5c83b4d](https://github.com/seuros/saga_machines/commit/5c83b4d32f62e4e8074f5cf1e08f9756bbc3ccfe))
+
+
+### Bug Fixes
+
+* depend on the published dedup-machines crate ([d3dc0aa](https://github.com/seuros/saga_machines/commit/d3dc0aaee5b40d7e969ab8973aac098c67b3411d))
+* name the gemspec block spec so the release workflow detects the extension ([fe76b8d](https://github.com/seuros/saga_machines/commit/fe76b8d64e1ba6677df891aa9037a57b030c64c9))

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,215 @@
+# SagaMachines
+
+> The return itinerary for expeditions that don't make it. 🔄
+
+A saga coordinator for Ruby. You tell it how many steps the journey has, it tells you which step to run next, you report how it went. When a step fails, it walks you back through every step that already succeeded, in reverse, until the world looks like you never left.
+
+## Quick Start
+
+```bash
+gem 'saga_machines'
+```
+
+```ruby
+saga = SagaMachines::Saga.new(order.id, steps: 3)
+
+while (action = saga.next_action)
+  outcome = case [action.kind, action.step]
+            when [:forward, 0]    then reserve_flight(order)
+            when [:forward, 1]    then reserve_hotel(order)
+            when [:forward, 2]    then reserve_car(order)
+            when [:compensate, 0] then release_flight(order)
+            when [:compensate, 1] then release_hotel(order)
+            when [:compensate, 2] then release_car(order)
+            end
+  saga.resolve(action, outcome ? :success : :failure)
+end
+
+saga.progress # => [:complete, nil] or [:aborted, nil]
+```
+
+That's the whole gem. One object, five methods, no DSL to memorize at 3 AM.
+
+## A Message to the Resistance
+
+So you shipped the checkout flow. Flight reserved, hotel reserved, then the car rental API returned a 503 and your customer now owns a hotel room in Lisbon with no way to get there.
+
+You know what the fix is. You've known since the first time you drew three boxes on a whiteboard and an arrow labeled "rollback" that nobody ever implemented. The fix is a saga: every forward step gets a compensating step, and when something breaks, you run the compensations in reverse order.
+
+The hard part was never the idea. The hard part is the bookkeeping. Which steps succeeded? Which compensation are we on? Did that retry already run? Can we still cancel? That bookkeeping is this gem. The reservations and the cancellations are still yours. We just promise never to lose count.
+
+## Chapter 1: Stardate 2025.186, the AMS Garcia-Molina
+
+> **AMS Garcia-Molina**, NCC-4217, *Garcia-Molina*-class recovery carrier.
+> A failed expedition needs a return itinerary, not a promise to reverse time.
+
+The carrier doesn't undo anything itself. It holds the flight plan. Three legs out, and if leg three is scrubbed, it orders legs two and one flown back, in that order, by the same crews that flew them out.
+
+Somewhere on the bridge, a junior officer suggests:
+
+```ruby
+def book_trip
+  reserve_flight
+  reserve_hotel
+  reserve_car
+rescue
+  # TODO: undo stuff
+end
+```
+
+"That," says the recovery officer, "is how customers end up owning hotel rooms."
+
+## The Flight Plan
+
+Every saga is in exactly one of four states. Two of them are final.
+
+```mermaid
+stateDiagram-v2
+    [*] --> forward
+    forward --> forward: step succeeds, more to go
+    forward --> complete: last step succeeds
+    forward --> compensating: step fails, earlier steps done
+    forward --> aborted: step fails or cancel, nothing done yet
+    forward --> compensating: cancel, earlier steps done
+    compensating --> compensating: compensation fails, same step retried
+    compensating --> compensating: compensation succeeds, earlier steps remain
+    compensating --> aborted: last compensation succeeds
+    complete --> [*]
+    aborted --> [*]
+```
+
+And here is the Lisbon trip, the day the car rental went down:
+
+```mermaid
+sequenceDiagram
+    participant You
+    participant Saga
+    participant Flight
+    participant Hotel
+    participant Car
+
+    You->>Saga: next_action
+    Saga-->>You: step 0, forward
+    You->>Flight: reserve
+    Flight-->>You: ok
+    You->>Saga: resolve(success)
+
+    You->>Saga: next_action
+    Saga-->>You: step 1, forward
+    You->>Hotel: reserve
+    Hotel-->>You: ok
+    You->>Saga: resolve(success)
+
+    You->>Saga: next_action
+    Saga-->>You: step 2, forward
+    You->>Car: reserve
+    Car-->>You: 503
+    You->>Saga: resolve(failure)
+
+    Note over Saga: compensating, step 1
+    You->>Saga: next_action
+    Saga-->>You: step 1, compensate
+    You->>Hotel: release
+    Hotel-->>You: ok
+    You->>Saga: resolve(success)
+
+    You->>Saga: next_action
+    Saga-->>You: step 0, compensate
+    You->>Flight: release
+    Flight-->>You: ok
+    You->>Saga: resolve(success)
+
+    Note over Saga: aborted. Nobody owns a hotel room.
+```
+
+## How a Journey Unfolds
+
+### Forward
+
+Each call to `next_action` hands you the next leg. It carries a `step` number and a `kind`, which is `:forward` on the way out.
+
+```ruby
+saga = SagaMachines::Saga.new(42, steps: 3)
+
+action = saga.next_action
+action.step  # => 0
+action.kind  # => :forward
+saga.resolve(action, :success)
+
+saga.progress # => [:forward, 1]
+```
+
+Resolve every step with `:success` and the saga lands at `[:complete, nil]`. `next_action` returns `nil` from then on. There is nothing left to do.
+
+### Something breaks
+
+Report `:failure` on a forward step and the saga turns around. It only compensates steps that actually succeeded, and it compensates them newest first.
+
+```ruby
+saga = SagaMachines::Saga.new(42, steps: 4)
+3.times { saga.resolve(saga.next_action, :success) } # steps 0, 1, 2 done
+
+failed = saga.next_action                           # step 3
+saga.resolve(failed, :failure)
+
+saga.progress     # => [:compensating, 2]
+saga.next_action  # => step 2, kind :compensate
+```
+
+Step 3 never succeeded, so it's never compensated. Step 2 is undone first, then 1, then 0. When the last compensation lands, progress reads `[:aborted, nil]`.
+
+### A compensation fails too
+
+Release-the-hotel can fail as easily as reserve-the-hotel. The saga doesn't skip it and doesn't give up. It hands you the same step again with a fresh attempt.
+
+```ruby
+undo = saga.next_action            # step 2, :compensate
+saga.resolve(undo, :failure)
+
+again = saga.next_action           # step 2, :compensate, new attempt
+undo.same_key?(again)              # => true, same leg
+saga.resolve(undo, :success)       # => false, that attempt is over
+saga.resolve(again, :success)      # => true
+```
+
+The old handle is dead. A late reply to a retry you already moved on from cannot advance the saga, no matter how convincing it looks.
+
+### Changing your mind
+
+`cancel` is allowed between actions, never during one. If a step is in flight, you don't get to pretend it isn't.
+
+```ruby
+saga = SagaMachines::Saga.new(7, steps: 2)
+saga.resolve(saga.next_action, :success)   # step 0 done, nothing pending
+
+saga.cancel      # => true
+saga.progress    # => [:compensating, 0]
+```
+
+Call `cancel` while an action is outstanding and it returns `false`. Resolve the action first, then cancel. A fresh saga with nothing done cancels straight to `[:aborted, nil]`.
+
+## The Rules of the Carrier
+
+- **Steps are exact.** `steps:` accepts 0, 1, 2, 3, 4, 8, or 16. Anything else raises `ArgumentError`. Zero steps is already complete.
+- **Identity is an Integer** in `0..2**64-1`. Use your order id, your job id, whatever you'd put on the manifest. Floats and strings raise `TypeError`.
+- **Every step is compensatable.** If you have a step that can't be undone, put it last, so nothing after it can fail.
+- **A forward failure means nothing happened.** If the car API timed out and you don't know whether it booked, find out before you report. Reporting `:failure` on a step that secretly succeeded is how you leak a car.
+- **Handles belong to one saga.** An action from one `Saga` instance is rejected by another, even with the same identity. `resolve` returns `false` for stale or foreign handles. It never raises for them.
+- **Frozen means frozen.** `freeze` the saga and every mutation raises `FrozenError`.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "I'll wrap it in a database transaction."
+### Reality: Stripe is not in your database.
+
+Transactions roll back rows. They do not unreserve a flight, refund a card, or recall an email. For anything that leaves your process, the only rollback is a forward action that cancels the previous one. That's a saga, and now you have one.
+
+## What's Yours
+
+The saga remembers where you are. It does not remember it for you across a crash. Persist the action before you execute it, persist the outcome before you resolve it, and on restart replay what you stored. It also doesn't schedule retries or wait for anything. Call `next_action` when you're ready, not before.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: In space, nobody can hear your rollback. But they can see the hotel charge on their statement.**

data/ext/saga_machines_native/core/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [0.3.1](https://github.com/seuros/saga_machines/compare/saga-machines-v0.3.0...saga-machines-v0.3.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* build against dedup-machines 0.3 ([fa36da9](https://github.com/seuros/saga_machines/commit/fa36da96c3aab595ff4daaa421a1f3e0d7c02fe9))
+
+## [0.3.0](https://github.com/seuros/saga_machines/compare/saga-machines-v0.2.2...saga-machines-v0.3.0) (2026-11-06)
+
+
+### Features
+
+* restore a saga from persisted progress ([6c98ddd](https://github.com/seuros/saga_machines/commit/6c98ddd8fc44b880dc8bf195f8d5a8e32048b423))
+
+## [0.2.2](https://github.com/seuros/saga_machines/compare/saga-machines-v0.2.1...saga-machines-v0.2.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([660b649](https://github.com/seuros/saga_machines/commit/660b649c5b0229ab715571ecb0b97270dcaacfab))
+
+## [0.2.1](https://github.com/seuros/saga_machines/compare/saga-machines-v0.2.0...saga-machines-v0.2.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([38c7ba8](https://github.com/seuros/saga_machines/commit/38c7ba8523f9ad783b258df3df15e2e2b5f3b6a0))
+
+## [0.2.0](https://github.com/seuros/saga_machines/compare/saga-machines-v0.1.0...saga-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([5c83b4d](https://github.com/seuros/saga_machines/commit/5c83b4d32f62e4e8074f5cf1e08f9756bbc3ccfe))

data/ext/saga_machines_native/core/README.md

@@ -0,0 +1,33 @@
+# saga-machines
+
+> **AMS Garcia-Molina**, NCC-4217, *Garcia-Molina*-class recovery carrier.
+
+Engine-room flight manual: chart forward maneuvers and compensating return legs.
+
+Allocation-free `no_std` sequential saga decisions. Successful forward steps are
+compensated in reverse order after a known forward failure. Failed compensations
+remain at the same step for a fresh retry attempt; stale/duplicate replies cannot
+advance progress. Every step is assumed compensatable. Cancellation is allowed
+only between actions, never by forgetting an unresolved external effect.
+
+Action keys remain stable across retries and can claim an external `dedup-machines`
+ledger. Attempt handles change to reject stale replies. A forward failure must mean
+**no effect occurred**; uncertain effects must be reconciled before reporting.
+Handles are scoped to one workflow lifetime.
+
+This model does not make effects or progress durable. Persist actions before
+executing them and outcomes before advancing; provide transactional/idempotent
+effects and crash recovery externally. Compensation is not atomic rollback.
+No payloads, retry timing, wire checkpoint, or Ruby binding.
+
+`snapshot()` exports the resolved progress and attempt count; `Saga::restore`
+rebuilds the workflow after a restart and rejects progress that does not fit the
+step count. An attempt that was issued but never resolved is not carried over:
+the restored saga reissues the same action key under a fresh attempt, so a reply
+to the pre-restart attempt is rejected and the external ledger decides whether
+the effect already happened.
+
+String identities such as manifest ids map to the `u64` namespace through
+`SagaId::from_bytes` (FNV-1a, deterministic across processes), so action keys
+stay stable across restarts. The caller owns collision avoidance within one
+ledger; `SagaId::from_raw` adopts an identity allocated elsewhere.

data/ext/saga_machines_native/extconf.rb

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

data/lib/saga_machines/version.rb

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

data/lib/saga_machines.rb

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

data/sig/saga_machines.rbs

@@ -0,0 +1,16 @@
+module SagaMachines
+  VERSION: String
+  class Action
+    def step: () -> Integer
+    def kind: () -> (:forward | :compensate)
+    def same_key?: (Action) -> bool
+  end
+  class Saga
+    def self.new: (Integer identity, steps: Integer) -> Saga
+    def steps: () -> Integer
+    def next_action: () -> Action?
+    def resolve: (Action, :success | :failure) -> bool
+    def cancel: () -> bool
+    def progress: () -> [Symbol, Integer?]
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: saga_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: x86_64-linux
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-06 00:00:00.000000000 Z
+dependencies: []
+description: Local unstable saga model, not a durable workflow or exactly-once runtime.
+email:
+- oss@seuros.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/saga_machines_native/core/CHANGELOG.md
+- ext/saga_machines_native/core/README.md
+- ext/saga_machines_native/extconf.rb
+- lib/saga_machines.rb
+- lib/saga_machines/version.rb
+- lib/saga_machines_native/saga_machines_native.so
+- sig/saga_machines.rbs
+homepage: https://github.com/seuros/saga_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/saga_machines
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: saga_machines_native
+  cargo_manifest_path: ext/saga_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: Initial native sequential saga and reverse compensation policies
+test_files: []