ruby_reactor 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70ff13eac6ccfdaafcad7bd36db33adf6efbf91e84d22967527c84625373b921
-  data.tar.gz: a6c599b3967660e6761e92caf071f3d81b9a0c9db074261a8e79322b8955644c
+  metadata.gz: 863c83e92cbfab470e39107c580ceabce444133973b723662a89e5bf0211c3ab
+  data.tar.gz: 1209b5587efc055bc787731694a6dc2b7eab8b3d5a6ff729728aa29ea601e2e0
 SHA512:
-  metadata.gz: 32326a6f81978625cc3447284b023e19c79b5b051adb115fe13291112f2db9b815a06dedef990ee9b903e93288023d0a97b5f319da6d01fe23229bfe9e5ab47a
-  data.tar.gz: 17f9361bd3222c82d4f098acb87a16244260c41b9ef13d990986351905d6ae7968448ce8639f460616a56c7fbdfeca64b789fbccbd4253e4080403581cbe0754
+  metadata.gz: 146d14cd32b12c95764e493f2de2d826dbe074ec4e4b44613b788d748d52fe38644fd86f1590f6bb0b1a0d1840c2200ab29a6d8e78db27f8f6abf099faf74756
+  data.tar.gz: 3d5b7c43182ee2d1c5c06ba90b7e2177a3dffbecdc8fb3e91db14f99bcd02807ebfa98c0e240412b790ec1d69609dc30995d9ee1aea9c8cb8ecd69d4d0fb2ac7

data/.rubocop.yml

@@ -13,6 +13,7 @@ AllCops:
     - bin/*
     - db/**/*
     - config/**/*
+    - demo_app/**/*
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
@@ -27,13 +28,13 @@ Metrics/BlockLength:
 Metrics/MethodLength:
   Exclude:
     - spec/**/*
-  Max: 25
+  Max: 36
   CountComments: false
 
 Metrics/ClassLength:
   Exclude:
     - spec/**/*
-  Max: 200
+  Max: 250
 
 Style/Documentation:
   Exclude:
@@ -96,3 +97,10 @@ RSpec/DescribeClass:
 
 RSpec/AnyInstance:
   Enabled: false
+
+Naming/VariableNumber:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Max: 200
+

data/README.md

@@ -1,7 +1,20 @@
+[![Gem Version](https://badge.fury.io/rb/ruby_reactor.svg)](https://badge.fury.io/rb/ruby_reactor)
+[![Build Status](https://github.com/arturictus/ruby_reactor/actions/workflows/main.yml/badge.svg)](https://github.com/arturictus/ruby_reactor/actions)  <!-- if you have CI -->
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
+[![Downloads](https://img.shields.io/gem/dt/ruby_reactor.svg)](https://rubygems.org/gems/ruby_reactor)
+
 # RubyReactor
 
+## Why Ruby Reactor?
+
+Building complex business transactions often results in spaghetti code or brittle "god classes." Ruby Reactor solves this by implementing the **Saga Pattern** in a lightweight, developer-friendly package. It lets you define workflows as clear, dependency-driven steps without the boilerplate of heavy enterprise frameworks.
+
+The key value is **Reliability**: if any part of your workflow fails, Ruby Reactor automatically triggers compensation logic to undo previous steps, ensuring your system never ends up in a corrupted half-state. Whether you're coordinating microservices or monolith modules, you get atomic-like consistency with background processing built-in.
+
 A dynamic, dependency-resolving saga orchestrator for Ruby. Ruby Reactor implements the Saga pattern with compensation-based error handling and DAG-based execution planning. It leverages **Sidekiq** for asynchronous execution and **Redis** for state persistence.
 
+![Payment workflow reactor](documentation/images/payment_workflow.png)
+
 ## Features
 
 - **DAG-based Execution**: Steps are executed based on their dependencies, allowing for parallel execution of independent steps.
@@ -9,8 +22,52 @@ A dynamic, dependency-resolving saga orchestrator for Ruby. Ruby Reactor impleme
 - **Map & Parallel Execution**: Iterate over collections in parallel with the `map` step, distributing work across multiple workers.
 - **Retries**: Configurable retry logic for failed steps, with exponential backoff.
 - **Compensation**: Automatic rollback of completed steps when a failure occurs.
+- **Interrupts**: Pause and resume workflows to wait for external events (webhooks, user approvals).
 - **Input Validation**: Integrated with `dry-validation` for robust input checking.
 
+## Comparison
+
+| Feature                  | Ruby Reactor | dry-transaction | Trailblazer | Custom Sidekiq Jobs |
+|--------------------------|--------------|-----------------|-------------|---------------------|
+| DAG/Parallel execution   | Yes          | No              | Limited     | Manual              |
+| Auto compensation/undo   | Yes          | No              | Manual      | Manual              |
+| Interrupts (pause/resume)| Yes          | No              | No          | Manual              |
+| Built-in web dashboard   | Yes          | No              | No          | No                  |
+| Async with Sidekiq       | Yes          | No              | Limited     | Yes                 |
+
+## Real-World Use Cases
+
+- **E-commerce Checkout**: Orchestrate inventory reservation, payment authorization, and shipping label generation. If payment fails, automatically release inventory and cancel the shipping request.
+- **Data Import Pipelines**: Ingest optional massive CSVs using `map` steps to validate and upsert records in parallel. If data validation fails for a chunk, fail fast or collect errors while letting valid chunks succeed.
+- **Subscription Billing**: Coordinate Stripe charges, invoice email generation, and internal entitlement updates. Use interrupts to pause the workflow when 3rd-party APIs are required to continue the workflow or when specific customer approval is needed.
+
+## Table of Contents
+- [Features](#features)
+- [Comparison](#comparison)
+- [Real-World Use Cases](#real-world-use-cases)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Quick Start](#quick-start)
+- [Web Dashboard](#web-dashboard)
+  - [Rails Installation](#rails-installation)
+- [Usage](#usage)
+  - [Basic Example: User Registration](#basic-example-user-registration)
+  - [Async Execution](#async-execution)
+    - [Full Reactor Async](#full-reactor-async)
+    - [Step-Level Async](#step-level-async)
+  - [Interrupts (Pause & Resume)](#interrupts-pause--resume)
+  - [Map & Parallel Execution](#map--parallel-execution)
+    - [Map with Dynamic Source (ActiveRecord)](#map-with-dynamic-source-activerecord)
+  - [Input Validation](#input-validation)
+  - [Complex Workflows with Dependencies](#complex-workflows-with-dependencies)
+  - [Error Handling and Compensation](#error-handling-and-compensation)
+  - [Using Pre-defined Schemas](#using-pre-defined-schemas)
+- [Documentation](#documentation)
+- [Future improvements](#future-improvements)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Code of Conduct](#code-of-conduct)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -47,6 +104,40 @@ RubyReactor.configure do |config|
 end
 ```
 
+
+## Quick Start
+
+```ruby
+class HelloReactor < RubyReactor::Reactor
+  step :greet do
+    run { Success("Hello from Ruby Reactor!") }
+  end
+  returns :greet
+end
+
+result = HelloReactor.run
+puts result.value  # => "Hello from Ruby Reactor!"
+```
+
+## Web Dashboard
+
+RubyReactor comes with a built-in web dashboard to inspect reactor executions, view logs, and retry failed steps.
+
+### Rails Installation
+
+Mount the dashboard engine in your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  # ... other routes
+  mount RubyReactor::Web::Application => '/ruby_reactor'
+end
+```
+
+![RubyReactor Dashboard Screenshot](documentation/images/failed_order_processing.png)
+
+You can secure the dashboard using standard Rails authentication methods (e.g., `authenticate` block with Devise).
+
 ## Usage
 
 RubyReactor allows you to define complex workflows as "reactors" with steps that can depend on each other, handle failures with compensations, and validate inputs.
@@ -198,6 +289,42 @@ def create(params)
 end
 ```
 
+### Interrupts (Pause & Resume)
+
+Pause execution to wait for external events like webhooks or user approvals.
+
+```ruby
+class ApprovalReactor < RubyReactor::Reactor
+  step :submit_request do
+    run { |args| RequestService.submit(args) }
+  end
+
+  interrupt :wait_for_manager do
+    wait_for :submit_request
+    # Resume using this ID
+    correlation_id { |ctx| "req-#{ctx.result(:submit_request)[:id]}" }
+  end
+
+  step :process_decision do
+    argument :decision, result(:wait_for_manager)
+    run do |args| 
+      args[:decision] == 'approved' ? Success() : Failure("Rejected")
+    end
+  end
+end
+
+# Usage:
+# 1. Start execution
+execution = ApprovalReactor.run(params) # => Returns Paused status
+
+# 2. Later, resume it via correlation ID
+ApprovalReactor.continue_by_correlation_id(
+  correlation_id: "req-123",
+  payload: "approved",
+  step_name: :wait_for_manager
+)
+```
+
 ### Map & Parallel Execution
 
 Process collections in parallel using the `map` step:
@@ -223,6 +350,42 @@ class DataProcessingReactor < RubyReactor::Reactor
 end
 ```
 
+By using `async true` with `batch_size`, the system applies **Back Pressure** to efficiently manage resources. [Read more about Back Pressure & Resource Management](documentation/data_pipelines.md#back-pressure--resource-management).
+
+#### Map with Dynamic Source (ActiveRecord)
+
+You can use a block for `source` to dynamically fetch data, such as from ActiveRecord queries. The result is wrapped in a `ResultEnumerator` for easy access to successes and failures.
+
+```ruby
+map :archive_old_users do
+  argument :days, input(:days)
+
+  # Dynamic source using ActiveRecord
+  source do |args|
+    User.where("last_login_at < ?", args[:days].days.ago)
+  end
+  
+  argument :user, element(:archive_old_users)
+  async true, batch_size: 100
+
+  step :archive do
+    argument :user, input(:user)
+    run { |args| args[:user].archive! }
+  end
+  
+  returns :archive
+end
+
+step :summary do
+  argument :results, result(:archive_old_users)
+  run do |args|
+    puts "Archived: #{args[:results].successes.count}"
+    puts "Failed: #{args[:results].failures.count}"
+    Success()
+  end
+end
+```
+
 ### Input Validation
 
 RubyReactor integrates with dry-validation for input validation:
@@ -540,6 +703,9 @@ Master the `map` feature for processing collections. Learn about parallel execut
 ### [Retry Configuration](documentation/retry_configuration.md)
 Configure robust retry policies for your steps. This guide details the available backoff strategies (exponential, linear, fixed), how to configure retries at the reactor or step level, and how async retries work without blocking workers.
 
+### [Interrupts](documentation/interrupts.md)
+Learn how to pause and resume reactors to handle long-running processes, manual approvals, and asynchronous callbacks. Patterns for correlation IDs, timeouts, and payload validation.
+
 ### Examples
 - [Order Processing](documentation/examples/order_processing.md) - Complete order processing workflow example
 - [Payment Processing](documentation/examples/payment_processing.md) - Payment handling with compensation
@@ -548,12 +714,20 @@ Configure robust retry policies for your steps. This guide details the available
 ## Future improvements
 
 - [X] Global id to serialize ActiveRecord classes
-- [ ] Middlewares
-- [ ] Descriptive errors
+- [X] Descriptive errors
 - [X] `map` step to iterate over arrays in parallel
 - [X] `compose` special step to execute reactors as step
+- [X] `interrupt` to pause and resume reactors
+- [ ] Middlewares
 - [ ] Async ruby to parallelize same level steps
-- [ ] Dedicated interface to inspect reactor results and errors
+- [x] Web dashboard to inspect reactor results and errors
+- [ ] Multiple storage adapters
+  - [X] Redis
+  - [ ] ActiveRecord
+- [ ] Multiple Async adapters
+  - [X] Sidekiq
+  - [ ] ActiveJob
+- [ ] OpenTelemetry support
 
 ## Development
 

data/Rakefile

@@ -5,6 +5,31 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
+namespace :build do
+  desc "Build the UI assets"
+  task :ui do
+    puts "Building UI..."
+    system("cd gui && npm install && npm run build") || abort("UI build failed")
+
+    # Copy assets to public
+    # Vite builds to dist by default. We want it in lib/ruby_reactor/web/public
+    # Actually, we should configure Vite to build to the right place or copy it.
+    # Let's copy.
+    FileUtils.rm_rf("lib/ruby_reactor/web/public")
+    FileUtils.mkdir_p("lib/ruby_reactor/web/public")
+    FileUtils.cp_r("gui/dist/.", "lib/ruby_reactor/web/public/")
+    puts "UI built and assets copied to lib/ruby_reactor/web/public"
+  end
+end
+
+namespace :server do
+  desc "Start the server"
+  task :start do
+    puts "Starting server..."
+    system("rackup -Ilib lib/ruby_reactor/web/config.ru -p 9292") || abort("Server failed to start")
+  end
+end
+
 require "rubocop/rake_task"
 
 RuboCop::RakeTask.new

data/documentation/data_pipelines.md

@@ -43,53 +43,35 @@ class UserTransformationReactor < RubyReactor::Reactor
 end
 ```
 
-## Async Execution
+## Dynamic Sources & ActiveRecord
 
-For long-running or resource-intensive tasks, you can offload processing to background jobs using Sidekiq.
-
-To enable async execution, simply add the `async true` directive to your map definition.
+The `map` step supports a dynamic `source` block, which is particularly useful when working with ActiveRecord or when the collection depends on input arguments. Instead of passing a static collection, you can define a block that returns an Enumerable or an `ActiveRecord::Relation`.
 
 ```ruby
-map :process_orders do
-  source input(:orders)
-  argument :order, element(:process_orders)
-  
-  # Enable async execution via Sidekiq
-  async true
-
-  step :charge_card do
-    argument :order, input(:order)
-    run { PaymentService.charge(args[:order]) }
+map :process_products do
+  argument :filter, input(:filter)
+
+  # Dynamic source block
+  source do |args|
+    # This block executes at runtime
+    threshold = args[:filter][:stock]
+    Product.where("stock >= ?", threshold)
   end
 
-  returns :charge_card
+  argument :product, element(:process_products)
+  async true, batch_size: 100
+
+  step :process do
+    # ...
+  end
+  
+  returns :process
 end
 ```
 
-### Execution Flow
-
-```mermaid
-sequenceDiagram
-    participant Reactor
-    participant Redis
-    participant Sidekiq
-    participant Worker
-
-    Reactor->>Redis: Store Context
-    Reactor->>Sidekiq: Enqueue MapElementWorkers
-    Note over Reactor: Returns AsyncResult immediately
-    
-    loop For each element
-        Sidekiq->>Worker: Process Element
-        Worker->>Redis: Update Element Result
-    end
-
-    Worker->>Sidekiq: Enqueue MapCollectorWorker (when done)
-    Sidekiq->>Worker: Run Collector
-    Worker->>Redis: Store Final Result
-```
+When an `ActiveRecord::Relation` is returned, RubyReactor efficiently batches the query using database-level `OFFSET` and `LIMIT` based on the configured `batch_size`, preventing memory bloat by not loading all records at once.
 
-## Batch Processing
+## Batch Processing Mechanism
 
 When processing large datasets asynchronously, you can control the parallelism using `batch_size`. This limits how many Sidekiq jobs are enqueued simultaneously, preventing system overload.
 
@@ -107,10 +89,42 @@ map :bulk_import do
 end
 ```
 
-**How it works:**
-1. The system initially enqueues `batch_size` jobs.
-2. As each job completes, it triggers the next job in the queue.
-3. This maintains a steady stream of processing without flooding the queue.
+### Back Pressure & Resource Management
+
+When `async true` is used with a `batch_size`, RubyReactor implements an intelligent **back pressure** mechanism. Instead of flooding Redis and Sidekiq with millions of jobs immediately (which is the standard behavior for many background job systems), the system processes data in controlled chunks.
+
+This approach provides critical benefits for stability and scalability:
+
+1.  **Memory Efficiency**: By using `ActiveRecord` batching (`LIMIT` / `OFFSET`), only the current batch of records is loaded into memory. This allows processing datasets larger than available RAM.
+2.  **Redis Protection**: Prevents "Queue Explosion". Only a small number of job arguments are stored in Redis at any time, preventing OOM errors in your Redis instance.
+3.  **Database Stability**: Database load is distributed over time rather than spiking all at once.
+
+**Visualizing the Flow:**
+
+```mermaid
+graph TD
+    Start[Start Map] -->|Batch Size: N| BatchManager
+    
+    subgraph "Back Pressure Loop"
+        BatchManager[Batch Manager] -->|Fetch N Items| DB[(Database)]
+        DB --> Records
+        Records -->|Enqueue N Jobs| Sidekiq
+        
+        Sidekiq --> W1[Worker 1]
+        Sidekiq --> W2[Worker 2]
+        
+        W1 -.->|Complete| Check{Batch Done?}
+        W2 -.->|Complete| Check
+        
+        Check -->|No| Wait[Wait]
+        Check -->|Yes| Next[Trigger Next Batch]
+        Next --> BatchManager
+    end
+    
+    BatchManager -->|No More Items| Finish[Aggregator]
+```
+
+This ensures that the system works at the speed of your workers, not the speed of the enqueueing process, maintaining a constant and manageable resource footprint regardless of dataset size.
 
 ## Error Handling
 
@@ -128,9 +142,9 @@ map :strict_processing do
 end
 ```
 
-### Collecting Partial Results
+### Collecting Results (Successes & Failures)
 
-If you want to process all elements regardless of failures, set `fail_fast false`. You can then use a `collect` block to handle successes and failures separately.
+If you want to process all elements regardless of failures, set `fail_fast false`. The map step returns a `ResultEnumerator` that allows you to easily separate successful executions from failures.
 
 ```ruby
 map :resilient_processing do
@@ -145,18 +159,39 @@ map :resilient_processing do
   end
 
   returns :risky_operation
+end
+
+step :analyze_results do
+  argument :results, result(:resilient_processing)
+  
+  run do |args|
+    col = args[:results]
+    
+    # Iterate over successful results
+    col.successes.each do |value|
+      # 'value' is the direct return value of the map element
+      puts "Success: #{value}"
+    end
+
+    # Iterate over failures
+    col.failures.each do |error|
+      # 'error' is the failure object/message itself
+      puts "Error: #{error}"
+    end
+
+    # Note: Iterating the collection directly yields wrapped objects
+    col.each do |result|
+      if result.is_a?(RubyReactor::Success)
+        puts "Wrapped Value: #{result.value}"
+      else
+        puts "Wrapped Error: #{result.error}"
+      end
+    end
 
-  # Aggregate results
-  collect do |results|
-    # results is an array of Result objects (Success or Failure)
-    successful = results.select(&:success?).map(&:value)
-    failed = results.select(&:failure?).map(&:error)
-
-    {
-      processed: successful,
-      errors: failed,
-      success_rate: successful.length.to_f / results.length
-    }
+    Success({
+      success_count: col.successes.count,
+      failure_count: col.failures.count
+    })
   end
 end
 ```
@@ -192,33 +227,4 @@ end
 - **Async Mode**: Retries are handled by requeuing the Sidekiq job with a delay. This is non-blocking and efficient.
 - **Sync Mode**: Retries happen immediately within the execution thread (blocking).
 
-## Visualization
 
-### Async Batch Execution
-
-```mermaid
-graph TD
-    Start[Start Map] --> Init[Initialize Batch]
-    Init --> Q1["Queue Initial Batch<br/>(Size N)"]
-    
-    subgraph Workers
-        W1[Worker 1]
-        W2[Worker 2]
-        W3[Worker ...]
-    end
-    
-    Q1 --> W1
-    Q1 --> W2
-    
-    W1 -->|Complete| Next1{More Items?}
-    W2 -->|Complete| Next2{More Items?}
-    
-    Next1 -->|Yes| Q2[Queue Next Item]
-    Next2 -->|Yes| Q2
-    
-    Q2 --> W3
-    
-    Next1 -->|No| Check{All Done?}
-    Check -->|Yes| Collect[Run Collector]
-    Collect --> Finish[Final Result]
-```

data/documentation/interrupts.md

@@ -0,0 +1,161 @@
+# Interrupts (Pause & Resume)
+
+RubyReactor introduces the `interrupt` mechanism to support long-running processes that require external input, such as user approvals, webhooks, or asynchronous job completions. Unlike standard steps that execute immediately, an `interrupt` pauses the reactor execution and persists its state, waiting for a signal to resume.
+
+## DSL Usage
+
+Use the `interrupt` keyword to define a pause point in your reactor.
+
+```ruby
+class ReportReactor < RubyReactor::Reactor
+  step :request_report do
+    run do
+      response = HTTP.post("https://api.example.com/reports")
+      Success(response.fetch(:id))
+    end
+  end
+
+  interrupt :wait_for_report do
+    # Declare dependency: execution must trigger this interrupt only after :request_report succeeds
+    wait_for :request_report
+
+    # Optional: deterministic correlation ID for looking up this execution later
+    correlation_id do |context|
+      "report-#{context.result(:request_report)}"
+    end
+
+    # Optional: timeout in seconds
+    # Strategies:
+    # - :lazy (default) - checked only when resume is attempted
+    # - :active - schedules a background job to wake up the reactor and fail it
+    timeout 1800, strategy: :active
+
+    # Optional: validate incoming payload immediately using dry-validation
+    validate do
+      required(:status).filled(:string)
+      required(:url).filled(:string)
+    end
+
+    # Optional: limit validation attempts (default: 1)
+    # If exhausted, the reactor is cancelled and compensated.
+    # Use :infinity for unlimited attempts.
+    max_attempts 3
+  end
+
+  step :process_report do
+    # The result of the interrupt step is the payload provided when resuming
+    argument :webhook_payload, result(:wait_for_report)
+
+    run do |args|
+      Success(ReportProcessor.call(args[:webhook_payload]))
+    end
+  end
+end
+```
+
+### Options
+
+*   **`wait_for`**: declare dependencies similar to `step`.
+*   **`correlation_id`**: A block that returns a unique string to identify this execution. This allows you to resume the reactor using a business key (e.g., order ID) instead of the internal execution UUID.
+*   **`timeout`**: Set a time limit for the interrupt.
+*   **`validate`**: A `dry-validation` schema block to validate the payload provided when resuming.
+*   **`max_attempts`**: Limit the number of times `continue` can be called with an invalid payload before the reactor is automatically cancelled and compensated. Defaults to 1. Set to `:infinity` for unlimited retries.
+
+## Runtime Behavior
+
+When a reactor encounters an `interrupt`:
+
+1.  It executes any dependencies.
+2.  It persists the full `Context` (results of previous steps) to the configured storage (e.g., Redis).
+3.  It returns an `InterruptResult` and halts execution.
+
+```ruby
+execution = ReportReactor.run(company_id: 1)
+
+if execution.paused?
+  execution.id         # => "uuid-123"
+  execution.status     # => :paused
+end
+```
+
+## Resuming Execution
+
+You can resume a paused reactor using its UUID or the defined `correlation_id`.
+
+### By UUID
+
+```ruby
+ReportReactor.continue(
+  id: "uuid-123",
+  payload: { status: "completed", url: "..." },
+  step_name: :wait_for_report
+)
+```
+
+### By Correlation ID
+
+```ruby
+ReportReactor.continue_by_correlation_id(
+  correlation_id: "report-999",
+  payload: { status: "completed", url: "..." },
+  step_name: :wait_for_report
+)
+```
+
+### Resuming Method Styles
+
+There are two ways to invoke continuation:
+
+1.  **Strict / Fire-and-Forget (Class Method)**:
+    *   `Reactor.continue(...)`
+    *   If payload is invalid, it **automatically compensates (undo)** and cancels the reactor.
+    *   Best for webhooks where you can't ask the sender to fix the payload.
+
+2.  **Flexible (Instance Method)**:
+    *   First find the reactor: `reactor = ReportReactor.find("uuid-123")`
+    *   Then call: `result = reactor.continue(payload: ..., step_name: :wait_for_report)`
+    *   If payload is invalid, it returns a failure result but **does not** cancel execution.
+    *   Allows you to handle the error (e.g., show a form error to a user) and try again.
+
+## Cancellation & Undo
+
+You can cancel a paused reactor if the operation is no longer needed.
+
+```ruby
+# Undo: Runs defined compensations for completed steps in reverse order, then deletes execution.
+ReportReactor.undo("uuid-123")
+
+# Cancel: Stops execution immediately and marks the reactor as cancelled with the provided reason.
+# The context is preserved for inspection, but resumption is disabled.
+ReportReactor.cancel("uuid-123", reason: "User cancelled")
+```
+
+## Common Use Cases
+
+### Human Approvals
+
+```ruby
+interrupt :wait_for_approval do
+  wait_for :submit_request
+  correlation_id { |ctx| "approval-#{ctx.input(:request_id)}" }
+end
+
+step :process_decision do
+  argument :decision, result(:wait_for_approval)
+  run do |args|
+    if args[:decision][:approved]
+      Success("Approved")
+    else
+      Failure("Rejected")
+    end
+  end
+end
+```
+
+### Webhooks
+
+Use `correlation_id` to map an external resource ID (like a Payment Intent ID) back to the reactor waiting for confirmation.
+
+### Scheduled Follow-ups
+
+Using `timeout` with `strategy: :active` to wake up a reactor after a delay if no external event occurs (e.g., expiring a reservation).