lepus-saga 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7886960ade3be84a12c25f22f85047e113bdd2ca19055b6f065624c15d1bb3af
+  data.tar.gz: 4cd2d1fd471c40db739ccb41dcef0bf52196a1a240f95c53404fced9bb264566
+SHA512:
+  metadata.gz: c1e827eb0eb4924c0951a5dd0c6aa08233fa141c7393e275ea0d19f1fbd5d038f2a675f7747762246814ec6dfca1f3ea6949fda0cc4d16ecc85c4ceda3891138
+  data.tar.gz: 3f9759919aa086d1afda979ee040010b549b9dd353944e4f5eb03a3373c6c2b9de4beaffb7a995cebf5ad30706aa19f43a880483bf3198ca65e274fb5a808d79

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.3.0 - Unreleased
+* Added: brand mark and README logo
+* Added: saga engine: `Lepus::Saga::Definition`, `Executor`, `ExecutorConsumer`, `StepProducer`, `QueueDepth`, `Instrumentation`, `LogSubscriber` and `Testing.drain`
+* Added: `Lepus::Saga.configure` with `store`, `exchange_name` (default `"lepus.saga"`), `max_resumes`, `backlog_threshold`, `backlog_patience` and `stale_running_attempt_after`
+* Added: ORM-agnostic persistence through `Lepus::Saga::Stores::Base`; `config.store = :name` requires `lepus/saga/stores/<name>`. ActiveRecord lives in the lepus-saga-active_record gem
+* Added: `Lepus::Saga::ExecutionBehaviour` and `StepAttemptBehaviour` for adapters' record classes
+* Added: `Lepus::Saga::Stores::Memory`, a thread-safe in-process store
+* Added: `require "lepus/saga/rspec"` with the "a lepus saga store" and "a lepus saga engine" shared examples
+* Added: `Lepus::Saga::ResumeStuckJob` ActiveJob for scheduling `Lepus::Saga.resume_stuck`
+* Changed: `resume_stuck` increments `resume_count` atomically instead of writing back the value it read
+* Added: optional query methods on `Stores::Base` (`queries?`, `list_executions`, `count_executions`, `execution_series`, `step_latency`, `failure_summary`, `saga_names`), implemented by `Stores::Memory`
+* Added: the "a lepus saga query store" shared examples in `lepus/saga/rspec`
+* Added: `Lepus::Saga.definitions`, the registry after eager loading the application
+* Added: `current_step` filter on `list_executions` and `count_executions`
+* Changed: `Stores::Memory` indexes step attempts by execution, so attempt lookups no longer scan every attempt
+* Added: `Lepus::Saga::Web`, a mountable Rack console (overview, executions, execution, insights) over the query methods, with `authorize`, `read_only`, `title`, `default_poll_interval` and `max_rows`; `rack >= 2.2` is a dependency
+* Added: `bin/web-demo`, the console on a seeded in-memory store
+* Added: `progress_from`/`progress_to` (last_progress_at) and `error_class`/`error_step`/`error_from`/`error_to` (a failed attempt) filters on `list_executions` and `count_executions`, and `execution_count` on `failure_summary` rows
+* Changed: the web console is a live map of saga lines with moving tokens, a 1 h/24 h/7 d range, full-width throughput, "Needs attention" and "Waiting the longest", and a poll picker; insights and the Barlow/Atkinson fonts are gone in favour of Overpass
+* Added: `Web` `stalled_after` setting; `/api/sagas` counts stalled executions per step, `/api/moving` lists the moving executions of the busiest steps in one request, and `/api/executions` takes `stalled`, `error`, `error_step`, `error_from` and `error_to`
+* Added: `HEAVY=1 bin/web-demo` seeds thousands of failures, a crowded step and hundreds of stalled executions
+* Changed: ActiveSupport is no longer a dependency. Durations are seconds (`ActiveSupport::Duration` still works), store names resolve through `Lepus::Primitive::String` and the shared examples run without ActiveSupport

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,237 @@
+PATH
+  remote: .
+  specs:
+    lepus-saga (0.3.0)
+      lepus (>= 0.2.1)
+      rack (>= 2.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activejob (8.1.4.1)
+      activesupport (= 8.1.4.1)
+      globalid (>= 0.3.6)
+    activesupport (8.1.4.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    amq-protocol (2.10.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.3)
+    bunny (3.5.0)
+      amq-protocol (~> 2.9)
+      logger (~> 1, >= 1.7)
+      openssl (>= 3.3)
+      sorted_set (~> 1, >= 1.0.2)
+    coderay (1.1.3)
+    concurrent-ruby (1.3.8)
+    connection_pool (3.0.2)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    globalid (1.4.0)
+      activesupport (>= 6.1)
+    i18n (1.15.2)
+      concurrent-ruby (~> 1.0)
+    io-console (0.9.5)
+    json (3.1.0)
+    language_server-protocol (3.17.0.6)
+    lepus (0.2.2)
+      base64
+      bunny
+      concurrent-ruby
+      multi_json
+      thor
+      zeitwerk
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    method_source (1.1.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    multi_json (1.21.2)
+    nio4r (2.7.5)
+    openssl (4.0.2)
+    parallel (2.3.0)
+    parser (3.3.13.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    pry (0.16.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+      reline (>= 0.6.0)
+    puma (8.0.2)
+      nio4r (~> 2.0)
+    racc (1.8.1)
+    rack (3.2.8)
+    rack-test (2.3.0)
+      rack (>= 1.3)
+    rackup (2.3.1)
+      rack (>= 3)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    rbtree (0.4.7)
+    regexp_parser (2.13.1)
+    reline (0.7.0)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.91.0)
+      json (>= 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rspec (3.10.2)
+      lint_roller (~> 1.1)
+      regexp_parser (>= 2.0)
+      rubocop (~> 1.86, >= 1.86.2)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    sorted_set (1.1.0)
+      rbtree
+    standard (1.57.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.91.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.9.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.26.0)
+    thor (1.5.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
+    uri (1.1.2)
+    zeitwerk (2.8.3)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  activejob
+  activesupport (>= 7.1)
+  lepus-saga!
+  pry
+  puma
+  rack-test
+  rackup
+  rake
+  rspec
+  rubocop
+  rubocop-performance
+  rubocop-rspec
+  standard
+
+CHECKSUMS
+  activejob (8.1.4.1) sha256=82c4c9311ea1016d5f7f134a0c5f9b6527cad5a6237f5f3f60aa17984ef36229
+  activesupport (8.1.4.1) sha256=16ac4f341ca65c85a1fcdb8ac73f68891aae9e3c4a6f9c3a27daed8b00017ed7
+  amq-protocol (2.10.0) sha256=98b3fe83837401cd0a7ff008faf4a454a56dc0e8c569c12db65c9225b63fd60e
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (4.1.3) sha256=61ebe1e5e559bdc3cc6f2c0ee7f427321fc838f59611c294356eb04d6e21cf66
+  bundler (4.0.18) sha256=02d9a17429de1847b4e0c9f27a9ee4b20c0a74c0a641b4e77195d6019e3618ac
+  bunny (3.5.0) sha256=34e3322fdc556ec2ab44e64413f0c2d412eac029207995d57fc5b26adc92cd5c
+  coderay (1.1.3) sha256=dc530018a4684512f8f38143cd2a096c9f02a1fc2459edcfe534787a7fc77d4b
+  concurrent-ruby (1.3.8) sha256=b2f1be836e968ccc78ccfce277ea79c72a88633f22306782c16ff23fb415d1e1
+  connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
+  globalid (1.4.0) sha256=037f12fbf1d9d7a014d501c2d5c77356fd4ddd96d7a7991d6700bba96706f427
+  i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
+  io-console (0.9.5) sha256=83dd9bbf4c4680416629245b39cd4212eb5f4d9a4ea91804870c1f6b846414d5
+  json (3.1.0) sha256=3ce7ccf8fde58960177a3a756c31f292a4c1e1dedee884547096a5b0604e3bd8
+  language_server-protocol (3.17.0.6) sha256=5ef2c0c138f8267e1bc631d3328347d354f96724b0af22f2c79516120443b7f0
+  lepus (0.2.2) sha256=7de6bcfb13e92b03af09d4a018c765aee6381624d8ace650705d5a87bea07fb7
+  lepus-saga (0.3.0)
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  method_source (1.1.0) sha256=181301c9c45b731b4769bc81e8860e72f9161ad7d66dd99103c9ab84f560f5c5
+  minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
+  multi_json (1.21.2) sha256=245531eaf54bdba57aba515ff08b4503505c5e09911daa89c5a561e2f85bea8e
+  nio4r (2.7.5) sha256=6c90168e48fb5f8e768419c93abb94ba2b892a1d0602cb06eef16d8b7df1dca1
+  openssl (4.0.2) sha256=1037ad2868ae58df9ad917891c0c0f9815a1172f6846d4bcdd508e4c2ee747c2
+  parallel (2.3.0) sha256=f75a3e904101ce6a1ccb6b8dc800cbafd42166d83330192438dcf29395167a6f
+  parser (3.3.13.0) sha256=e02f9b63c2fe05b0c68f692ba4df89b3cb113b663964f75d988fbebfd6c3deca
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  pry (0.16.1) sha256=d92d82c86e7f2dc34beec6d2892d5cf5ea517eea22eed3ceabb38ee62a98accc
+  puma (8.0.2) sha256=c8ed871dfbbe66448ea9ffd46692342d9804d4071522b52b5331b7b6e7b686fb
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rack (3.2.8) sha256=1fecc85e463ebc7a2a945fff829ffcd549babeb1556384796fad946c28dc4ec7
+  rack-test (2.3.0) sha256=b118d177cc002c572fc1b6fd8d19c9ed5881a36e8d6f689f9e618f9f861241e8
+  rackup (2.3.1) sha256=6c79c26753778e90983761d677a48937ee3192b3ffef6bc963c0950f94688868
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  rbtree (0.4.7) sha256=1efabbcb3fd5f12249c9c8a610a765074868164eed0c50c9db2531c00ed161cb
+  regexp_parser (2.13.1) sha256=5aedb6b7c35688f51e86eef17a15374dfd287c83f4ca644b2c5f3ec50a33b44b
+  reline (0.7.0) sha256=5b012d8e55dbf9d450f12bde2cf7d15ff546ae80b3f8f3b30e570d431815583d
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  rubocop (1.91.0) sha256=9c82b7bf391c5d7e3798c5b9996e22a1fe3bd7468e351dfdeb96140c058296d0
+  rubocop-ast (1.50.0) sha256=b9ca88300da0803ee222ad20cdb30494c0a784eed06fdc35d254b06d662788db
+  rubocop-performance (1.26.1) sha256=cd19b936ff196df85829d264b522fd4f98b6c89ad271fa52744a8c11b8f71834
+  rubocop-rspec (3.10.2) sha256=0b3e2ecc592cd10ecbf0095bb58d1e357905276e069643523cc19eb7495f65e2
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
+  sorted_set (1.1.0) sha256=bac01eb16b6bcfcdb7d732a28e87422be8b5c9fdcfeadbe9072682407524ee83
+  standard (1.57.0) sha256=4a65ea92421fbaf77fb54da91e16093cf79b335b8f62c35aaa3dd714c8592858
+  standard-custom (1.0.2) sha256=424adc84179a074f1a2a309bb9cf7cd6bfdb2b6541f20c6bf9436c0ba22a652b
+  standard-performance (1.9.0) sha256=49483d31be448292951d80e5e67cdcb576c2502103c7b40aec6f1b6e9c88e3f2
+  thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
+  tzinfo (2.0.6) sha256=8daf828cc77bcf7d63b0e3bdb6caa47e2272dcfaf4fbfe46f8c3a9df087a829b
+  unicode-display_width (3.3.0) sha256=4b7aa66a4b11db50f6f7e98411215cd0dd10eaecb665d36eec5bcacb3fa0b613
+  unicode-emoji (4.3.0) sha256=11c02fa73290378c066bb0562cd4c87d8e1b706fbbe0059ca12746a4244de8ce
+  uri (1.1.2) sha256=89292e98eabbef6248b0a0ed5e7e398e152f83f17560023a6d94a7f492b169fb
+  zeitwerk (2.8.3) sha256=2c85125a8467ce069e20123d1e709a08955c9d29c118c25b46b7b7fafdbb92e5
+
+BUNDLED WITH
+  4.0.18

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Marcos G. Zimmermann
+
+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,337 @@
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/brand/lockup-lepus-saga-on-dark.svg">
+    <img alt="Lepus saga" src="docs/brand/lockup-lepus-saga-on-light.svg" width="359">
+  </picture>
+</h1>
+
+Linear sagas on top of [Lepus](https://github.com/marcosgz/lepus).
+
+A saga is an ordered list of steps with optional compensations and retry policies. State lives in a store: one execution per saga run and one step attempt per try of a step. Messages on the saga exchange only point at the next unit of work, so duplicate deliveries are fenced out, and lost messages are healed by re-publishing whatever the execution record says is current.
+
+This gem is the engine and has no ORM dependency. Storage comes from an adapter:
+
+| Store | Gem | `config.store =` |
+| --- | --- | --- |
+| ActiveRecord (PostgreSQL, MySQL/MariaDB, SQLite) | [lepus-saga-active_record](https://github.com/marcosgz/lepus-saga-active_record) | `:active_record` |
+| Sequel (PostgreSQL, MySQL/MariaDB, SQLite) | [lepus-saga-sequel](https://github.com/marcosgz/lepus-saga-sequel) | `:sequel` |
+| In-process memory (tests, scripts) | this gem | `:memory` |
+
+## Installation
+
+lepus-saga runs on plain Ruby and does not depend on ActiveSupport. Like Lepus, it fits into Rails when ActiveSupport is there: durations such as `15.minutes` are accepted wherever seconds are, engine events reach `ActiveSupport::Notifications`, and the optional `Lepus::Saga::ResumeStuckJob` runs on ActiveJob.
+
+```ruby
+gem "lepus-saga"
+gem "lepus-saga-active_record"
+```
+
+```bash
+bundle install
+bin/rails generate lepus:saga:install
+bin/rails db:migrate
+```
+
+With Sequel, add `gem "lepus-saga-sequel"` instead, create the tables with `Lepus::Saga::Sequel.migrate(DB)` and set `config.store = :sequel` (see the [lepus-saga-sequel README](https://github.com/marcosgz/lepus-saga-sequel#readme)).
+
+## Configuration
+
+```ruby
+# config/initializers/lepus_saga.rb
+Lepus::Saga.configure do |config|
+  config.store = :active_record                  # a name, a store class or a store instance
+  config.exchange_name = "lepus.saga"            # topic exchange; queues are "<exchange>.execute[.<partition>]"
+  config.max_resumes = 5                         # re-publishes of a stalled execution before it is abandoned
+  config.backlog_threshold = 100                 # ready messages above which a partition counts as backlogged
+  config.backlog_patience = 2 * 3600             # seconds stalled behind a backlog before one re-publish
+  config.stale_running_attempt_after = 5 * 60    # seconds after which a running attempt is closed as abandoned
+end
+```
+
+Durations are seconds. With ActiveSupport loaded, `2.hours` and other `ActiveSupport::Duration` values work as well.
+
+Configure it before the consumer classes load, because `saga_partition` reads the exchange and queue names when the class body runs.
+
+A store name is resolved the way Esse resolves plugins: `:active_record` requires `lepus/saga/stores/active_record` (shipped by the adapter gem) and instantiates `Lepus::Saga::Stores::ActiveRecord`. `Lepus::Saga.store` returns the configured instance and raises `Lepus::Saga::ConfigurationError` when there is none.
+
+## Defining a saga
+
+```ruby
+class Orders::CheckoutSaga < Lepus::Saga::Definition
+  saga_name "orders.checkout"
+  partition "default"
+
+  step :reserve_stock, compensate: :release_stock, retry: { attempts: 5 }
+  step :persist_local
+
+  def reserve_stock
+    context["reservation_id"] = Inventory.reserve(resource)
+  end
+
+  def release_stock
+    Inventory.release(context["reservation_id"])
+  end
+
+  def persist_local
+    skip!("already persisted") if resource.persisted_remotely?
+    resource.update!(reservation_id: context["reservation_id"])
+  end
+end
+
+Orders::CheckoutSaga.start(resource: order, context: { "name" => order.name })
+Orders::CheckoutSaga.start(resource: { type: "Order", id: "abc" }, partition: "priority")
+```
+
+Step methods run with `execution`, `context`, `resource` and `step_attempt`. Changes to `context` are saved when the step succeeds. Delivery is at-least-once, so steps must be idempotent. `resource` is `resource_type.constantize.find(resource_id)`; override `find_resource` for anything else.
+
+Inside a step:
+
+- `skip!(reason = nil)` records the step as skipped and continues.
+- `complete!(reason = nil)` finishes the execution successfully right away.
+- `fail!(reason)` fails without retrying and compensates the succeeded steps.
+- Any other exception is retried up to the step's `retry:` attempts (default 3), then compensated.
+
+Call `start` after the transaction that changed the resource has committed.
+
+## Consumers
+
+Declare one executor consumer per partition:
+
+```ruby
+class SagaExecutorConsumer < Lepus::Saga::ExecutorConsumer
+  saga_partition "default", worker: { name: "saga", threads: 5 }, retry_delay: 10_000
+end
+```
+
+Failed attempts are rejected into a TTL retry queue (`retry_delay` in milliseconds), and the error queue is enabled.
+
+## Operations
+
+```ruby
+Lepus::Saga.retry(execution)                     # restart a failed/stuck execution from its current step
+Lepus::Saga.compensate(execution, reason: "...") # force compensation of a non-terminal execution
+Lepus::Saga.resume_stuck(older_than: 15 * 60, limit: 100, max_resumes: Lepus::Saga.config.max_resumes)
+```
+
+`retry` and `compensate` lock the execution, reload the record you pass in place and return it.
+
+`resume_stuck` re-publishes executions whose cursor has not moved for `older_than` seconds. An execution re-published `max_resumes` times without progress is compensated, or failed when there is nothing to undo. While a partition's queue holds more than `backlog_threshold` ready messages, its executions are left alone and re-published once after `backlog_patience`.
+
+Schedule it with the bundled ActiveJob (`require "lepus/saga/resume_stuck_job"`, needs `activejob`), e.g. in Solid Queue's `config/recurring.yml`:
+
+```yaml
+saga_resume_stuck:
+  class: Lepus::Saga::ResumeStuckJob
+  args: [15]
+  schedule: every 5 minutes
+```
+
+Without ActiveJob, call it from any scheduler:
+
+```ruby
+class SagaResumeStuckWorker
+  include Sidekiq::Job
+
+  def perform = Lepus::Saga.resume_stuck(older_than: 15 * 60)
+end
+```
+
+Reads go through the store too, so they work with any adapter:
+
+```ruby
+store = Lepus::Saga.store
+store.find_execution(id)
+store.executions_for_resource("Order", order.id) # newest first
+store.step_attempts(execution)                       # chronological
+```
+
+Adapters usually offer richer queries on their own records (`Lepus::Saga::ActiveRecord::Execution.for_resource(...).completed`).
+
+## Web console
+
+`Lepus::Saga::Web` is a Rack app for the engineer on call. It has three screens:
+
+- **Map**: every saga drawn as a line of its steps. Tokens are the executions moving right now, placed along the step by how long they have spent in it against the step's median, up to three lanes per step and a "+N running" pill for the rest (static when the viewer prefers reduced motion). Each step shows its stalled executions and its failures in the selected time range (1 h, 24 h or 7 d, kept in the URL). The headline reads as the key: how many executions are moving, compensating and stalled, and how many failed. Below the map, a full-width throughput chart (with a table view), **Needs attention** (failed attempts grouped by error, saga and step, each linking to exactly the executions that failed that way in the range) and **Waiting the longest** (the stalled executions with the oldest progress).
+- **Executions**: a paged list filtered by status, saga, step, error, time range or stalled.
+- **Execution**: a replay of the execution along its line, its attempt history with errors and backtraces, its context and other runs of the same resource. Retry and compensate are one click plus a confirmation.
+
+It reads through the store's optional query methods, so the store must report `queries?` (`Stores::Memory`, `Stores::ActiveRecord` and `Stores::Sequel` do).
+
+```ruby
+require "lepus/saga/web"
+```
+
+It has no authentication of its own: mount it behind yours. In Rails, with Devise:
+
+```ruby
+# config/routes.rb
+authenticate :user, ->(user) { user.admin? } do
+  mount Lepus::Saga::Web => "/workflows"
+end
+```
+
+or with a route constraint:
+
+```ruby
+constraints(->(request) { request.env["warden"].user&.admin? }) do
+  mount Lepus::Saga::Web => "/workflows"
+end
+```
+
+In a plain `config.ru`:
+
+```ruby
+require "lepus/saga/web"
+
+use Rack::Auth::Basic, "SAGA" do |user, password|
+  Rack::Utils.secure_compare(user, ENV.fetch("LEPUS_SAGA_USER")) & Rack::Utils.secure_compare(password, ENV.fetch("LEPUS_SAGA_PASSWORD"))
+end
+run Lepus::Saga::Web
+```
+
+The console works under any mount path: the page's `<base href>` is the mount point and every URL in it is relative.
+
+```ruby
+Lepus::Saga::Web.configure do |config|
+  config.authorize = ->(env, action) { action == :read || env["warden"].user&.admin? } # :read, :retry or :compensate
+  config.read_only = false          # true hides retry and compensate and refuses them
+  config.title = "SAGA"
+  config.default_poll_interval = 5  # seconds: 0, 2, 5, 15 or 60
+  config.max_rows = 50_000          # rows read for the throughput series and step latency
+  config.stalled_after = 15 * 60    # seconds without progress before an in-progress execution counts as stalled
+end
+```
+
+`authorize` runs on every request: a falsy answer for `:read` returns 403 for the whole console, and for `:retry` or `:compensate` it refuses that action and the page hides its button. Retry and compensate are POSTs that need a JSON body, an `X-Lepus-Saga` header and a same-origin `Origin` (or `Referer`), so a cookie-authenticated session cannot be driven from another site.
+
+The page refreshes itself by polling the JSON API. The Live button in the top bar picks the interval: Paused, 2, 5, 15 or 60 seconds (`default_poll_interval` until the viewer picks one). Polling also pauses while the tab is hidden, and the map's tokens freeze while paused. The theme follows the system, or Light or Dark when picked; the interval, the theme and the time range are kept in the browser.
+
+Content Security Policy: the console loads only its own files (no inline scripts or styles, no `eval`, no CDN) and sends `default-src 'self'` with its page. A host-wide policy works as long as it allows `'self'` for scripts, styles, fonts and fetches, and `data:` images. Static files are served with ETags; the page references them under a digest path, cached for a year.
+
+To see the console without a database or RabbitMQ, run `bin/web-demo` from a checkout: it seeds an in-memory store with a week of executions generated by the real engine, keeps starting new ones, and serves the console on http://127.0.0.1:9292 (`PORT`, `HOST` and `DAYS` change it). `HEAVY=1` adds the load of a bad day: thousands of failed attempts, hundreds of executions crowding one step and hundreds of stalled ones. It is not part of the gem.
+
+The font is Overpass, under the SIL Open Font License (`web/assets/fonts/overpass/OFL.txt`).
+
+## Instrumentation and logging
+
+Events go through `Lepus.instrument`, which publishes them to `ActiveSupport::Notifications` when it is loaded and does nothing otherwise. They are suffixed with `.lepus`: `saga.started`, `saga.step.started`, `saga.step.finished`, `saga.step.failed`, `saga.step.skipped`, `saga.completed`, `saga.compensation_started`, `saga.compensated`, `saga.failed`, `saga.compensation_failed`, `saga.resumed`. The payload carries the execution record under `:execution`.
+
+```ruby
+ActiveSupport::Notifications.subscribe(/\Asaga\./) do |name, _started, _finished, _id, payload|
+  Lepus::Saga::LogSubscriber.call(name.delete_suffix(".lepus"), payload)
+end
+```
+
+`LogSubscriber` writes one `key=value` line per event to `Lepus.logger`, at debug for step progress, warn for step failures and error for failed sagas.
+
+## Testing
+
+```ruby
+require "lepus/saga/testing"
+
+Lepus::Testing.enable!
+Orders::CheckoutSaga.start(resource: order)
+Lepus::Saga::Testing.drain(consumer: SagaExecutorConsumer)
+```
+
+`drain` delivers the fake saga exchange's messages to the consumer until it is empty, redelivering rejected messages right away so retries run inline. It raises `Lepus::Saga::Testing::DrainStallError` after `max_iterations` (default 50).
+
+Tests that should not touch a database can run on the memory store: `Lepus::Saga.config.store = :memory`, and `Lepus::Saga.store.clear!` between examples.
+
+## Architecture
+
+```
+Definition.start ──> store.create_execution ──> StepProducer ──> saga exchange
+                                                                       │
+ExecutorConsumer <─────────────────────────────────────────────────────┘
+      │
+      └─> Executor
+            prepare:  store.with_locked_execution (fence epoch/step/direction, close
+                      abandoned attempts, count them, store.create_step_attempt)
+            run step: no lock held (user code may be slow)
+            finish:   store.with_locked_execution (finish the attempt, move the cursor)
+```
+
+- `Definition`, `Executor`, `ExecutorConsumer`, `StepProducer`, `QueueDepth`, `Instrumentation`, `LogSubscriber` and `Testing` only talk to `Lepus::Saga.store`.
+- `Lepus::Saga::Stores::Base` is the persistence contract. Every method is documented in [`lib/lepus/saga/stores/base.rb`](lib/lepus/saga/stores/base.rb).
+- `Lepus::Saga::ExecutionBehaviour` and `Lepus::Saga::StepAttemptBehaviour` hold what records mean: statuses and predicates (`running?`, `terminal?`, `compensate_direction?`), `record_progress`, `definition_class`, `partition`, `current_step_scope`, `duration` and `finish_attributes`. Adapters include them into their own record classes.
+
+### The store contract
+
+| Method | Semantics |
+| --- | --- |
+| `create_execution(attributes)` | Inserts an execution with a UUIDv7 id; defaults status `running`, direction `execute`, epoch and resume_count 0, context `{}` |
+| `find_execution(id)` | The record or nil, never locked |
+| `save_execution(execution)` | Persists the record's attributes, returns it |
+| `with_lock(execution) { }` | Exclusive row lock for the block after reloading the record in place; writes kept on return (including `next`), discarded on raise; returns the block value |
+| `with_locked_execution(id) { \|execution_or_nil\| }` | Same, from an id; Base implements it with `find_execution` + `with_lock`, adapters may do it in one query |
+| `increment_resume_count(execution)` | One atomic `resume_count = resume_count + 1` that touches updated_at; sets and returns the stored value |
+| `stalled_executions(before:)` | Running or compensating executions with `last_progress_at < before`, oldest first, as an Enumerable the caller may stop early |
+| `executions_for_resource(type, id)` | A resource's executions, newest first |
+| `create_step_attempt(execution, attributes)` | Inserts a `running` attempt; a second one with the same execution, step, direction, epoch and attempt raises `Lepus::Saga::DuplicateAttemptError` |
+| `save_step_attempt(attempt)` | Persists the attempt, returns it |
+| `step_attempts(execution)` | Attempts ordered by started_at, created_at |
+| `count_step_attempts(execution, step_name:, direction:, epoch:)` | Attempts for that step, any status |
+| `running_step_attempt?(execution, step_name:, direction:, epoch:, started_since:)` | A `running` attempt started at or after the cutoff exists |
+| `stale_step_attempts(execution, step_name:, direction:, epoch:, started_before:)` | `running` attempts started before the cutoff |
+| `step_succeeded?(execution, step_name)` | A `succeeded` attempt in the execute direction exists, any epoch |
+
+Base builds `update_execution`, `update_step_attempt` and `finish_step_attempt` on top of these.
+
+The query methods are optional. The engine never calls them; read-only tools such as dashboards do, after checking `queries?`. Base raises `NotImplementedError` from each and returns false from `queries?`.
+
+| Method | Semantics |
+| --- | --- |
+| `queries?` | Whether the store implements the methods below |
+| `list_executions(saga_name:, status:, current_step:, partition:, resource:, from:, to:, progress_from:, progress_to:, error_class:, error_step:, error_from:, error_to:, before_id:, limit: 50)` | Executions newest first by id, `limit` of them, the page after `before_id` when given. Every filter is optional: `saga_name`, `status` and `current_step` take a value or a list, `partition` matches the column or (when it is nil) the definition's partition, `resource` is a case-insensitive substring of resource_type or resource_id, `from`/`to` bound created_at and `progress_from`/`progress_to` bound last_progress_at (inclusive/exclusive), `error_class` and `error_step` (a value or a list) keep executions with a failed attempt of that error class at that step, started between `error_from` and `error_to` when given |
+| `count_executions(group_by:, **filters)` | A Hash of counts keyed by `:saga_name`, `:status`, `:partition` or `:current_step`, or by arrays of values for an array such as `[:saga_name, :status]`; partition groups resolve nil to the definition's partition |
+| `execution_series(from:, to:, bucket:, saga_name: nil, max_rows:)` | `{rows: [[bucket_start, {"started" => n, "completed" => n, "compensated" => n, "failed" => n, "compensation_failed" => n}], ...], truncated:}`: starts by created_at, terminal statuses by finished_at, every bucket of the window aligned to multiples of `bucket` seconds, at most `max_rows` timestamps of each kind (the newest) |
+| `step_latency(from:, to:, saga_name: nil, max_rows:)` | `{rows: [{saga_name:, step_name:, direction:, count:, p50:, p95:, p99:, max:}, ...], truncated:}`: nearest-rank percentiles in milliseconds of succeeded and failed attempts started in the window, from the newest `max_rows` |
+| `failure_summary(from:, to:, saga_name: nil, limit: 20)` | `[{error_class:, saga_name:, step_name:, count:, execution_count:, last_seen_at:, sample_message:, sample_execution_id:}, ...]`: failed attempts started in the window grouped by error class, saga and step, most frequent first, `execution_count` being the distinct executions and the sample the latest failure |
+| `saga_names` | The distinct saga names in storage, sorted |
+
+`max_rows` defaults to `Stores::Base::QUERY_MAX_ROWS` (50,000), and a series may hold at most 1,000 buckets. Stores compute buckets and percentiles in Ruby with the helpers Base provides, so they need nothing beyond filters, grouping and counting from their backend.
+
+The engine changes an execution only inside `with_lock`/`with_locked_execution`. The two writes made without the lock are the atomic `increment_resume_count` and closing an attempt the worker opened itself. A store therefore needs a real exclusive lock (`SELECT ... FOR UPDATE` or an equivalent), atomic increments and a unique index on attempts. It does not need optimistic locking.
+
+### Writing an adapter
+
+1. Create a gem named `lepus-saga-<name>` with `lib/lepus/saga/stores/<name>.rb` defining `Lepus::Saga::Stores::<Name> < Lepus::Saga::Stores::Base`, so `config.store = :<name>` finds it.
+2. Give it record classes that include `Lepus::Saga::ExecutionBehaviour` and `Lepus::Saga::StepAttemptBehaviour`. They need readers and writers for each behaviour's `ATTRIBUTES`, and `[](name)` returning the raw stored value. The behaviour's `partition` (the column, or the definition's partition when it is nil) must win over the column reader. ActiveRecord and Sequel define column readers in a module below the class, so including the behaviour in the class body is enough; check that your ORM does the same.
+3. Implement every method of `Stores::Base` that raises `NotImplementedError`.
+4. Run the shared examples:
+
+```ruby
+# spec/lepus/saga/stores/my_store_spec.rb
+require "lepus/saga/rspec"
+
+RSpec.describe Lepus::Saga::Stores::MyStore do
+  let(:store) { described_class.new }
+
+  after { DB[:saga_step_attempts].delete && DB[:saga_executions].delete }
+
+  it_behaves_like "a lepus saga store"   # every store method, including locks across threads
+  it_behaves_like "a lepus saga engine"  # the executor, retry, compensate and resume_stuck end to end
+end
+```
+
+Both accept `concurrency: false` to skip the threaded examples on a backend that cannot share data between threads.
+
+5. Optionally implement the query methods, return true from `queries?` and add `it_behaves_like "a lepus saga query store"`. An adapter without them keeps working with the engine; tools that need them check `queries?` first.
+
+[lepus-saga-active_record](https://github.com/marcosgz/lepus-saga-active_record) and [lepus-saga-sequel](https://github.com/marcosgz/lepus-saga-sequel) are complete adapters to start from: models, store, migrations and the shared examples run on PostgreSQL, MySQL/MariaDB and SQLite.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rspec       # memory store
+BUNDLE_GEMFILE=ci/Gemfile.no_activesupport bundle install
+BUNDLE_GEMFILE=ci/Gemfile.no_activesupport bundle exec rspec  # without ActiveSupport or ActiveJob
+bundle exec rubocop
+bin/web-demo            # the web console on a seeded memory store
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec