chrono_forge 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b16c027867c5aca8d3f168ccb252125feef563731af33f40a129bfa9bfb781c5
-  data.tar.gz: 0ebd43e1896ea8df4ceb00c9c9af49c57a1e74d309149e817e43f9acfdfd5b8a
+  metadata.gz: cbb73c055f7439bc5e787d68a6d46bbb687143a85a3d57dcade8910aaae93916
+  data.tar.gz: 7b40ca8cc17398e695434c3e1ab61c7cfa12dfeb0ac941dd257daa18b633dbed
 SHA512:
-  metadata.gz: c94edc3ed7339bf3c7304c54e547bb1f86bc098dda586ffa049cfaf2fc29efcc7b44cce9429789ee1c3c5559dd3dd75859b75e74a27587c2a804160fee600f42
-  data.tar.gz: f7350954cace2c26ca57c7c0253a81d098a2eb655a5f283e6627eedec9d2b4acc11e0f58d3bebe47cd8a4c82907e1c4410d3655c43695ec8f02b8cc0af6a52c2
+  metadata.gz: 0a6db6125a515d250b19ba3bd59db16056973a0d23df3acf76b5341a7990f962694dec5b9732302a0a850844c62a97847640c289bdebcee0f684f691e214049f
+  data.tar.gz: 852d241932f2cfc28e48bb6713f79d0c5086dfe8f92b92828f6ef03943250c548cef331de43d208d756c209ea99633f3ab99229391dd8c207fed47b6e4bf31f4

data/README.md

@@ -47,17 +47,45 @@ $ rails db:migrate
 
 ## 📋 Usage
 
+### Creating and Executing Workflows
+
+ChronoForge workflows are ActiveJob classes that prepend the `ChronoForge::Executor` module. Each workflow can **only** accept keyword arguments:
+
+```ruby
+# Define your workflow class
+class OrderProcessingWorkflow < ApplicationJob
+  prepend ChronoForge::Executor
+  
+  def perform(order_id:, customer_id:)
+    # Workflow steps...
+  end
+end
+```
+
+All workflows require a unique identifier when executed. This identifier is used to track and manage the workflow:
+
+```ruby
+# Execute the workflow
+OrderProcessingWorkflow.perform_later(
+  "order-123",                 # Unique workflow key
+  order_id: "order-134",       # Custom kwargs
+  customer_id: "customer-456"  # More custom kwargs
+)
+```
+
 ### Basic Workflow Example
 
 Here's a complete example of a durable order processing workflow:
 
 ```ruby
 class OrderProcessingWorkflow < ApplicationJob
-  include ChronoForge::Executor
+  prepend ChronoForge::Executor
+
+  def perform(order_id:)
+    @order_id = order_id
 
-  def perform
     # Context can be used to pass and store data between executions
-    context.set_once "order_id", SecureRandom.hex
+    context.set_once "execution_id", SecureRandom.hex
 
     # Wait until payment is confirmed
     wait_until :payment_confirmed?
@@ -75,16 +103,16 @@ class OrderProcessingWorkflow < ApplicationJob
   private
 
   def payment_confirmed?
-    PaymentService.confirmed?(context["order_id"])
+    PaymentService.confirmed?(@order_id, context["execution_id"])
   end
 
   def process_order
-    OrderProcessor.process(context["order_id"])
+    OrderProcessor.process(@order_id, context["execution_id"])
     context["processed_at"] = Time.current.iso8601
   end
 
   def complete_order
-    OrderCompletionService.complete(context["order_id"])
+    OrderCompletionService.complete(@order_id, context["execution_id"])
     context["completed_at"] = Time.current.iso8601
   end
 end
@@ -92,6 +120,28 @@ end
 
 ### Core Workflow Features
 
+#### 🚀 Executing Workflows
+
+ChronoForge workflows are executed through ActiveJob's standard interface with a specific parameter structure:
+
+```ruby
+# Perform the workflow immediately
+OrderProcessingWorkflow.perform_now(
+  "order-123",                     # Unique workflow key
+  order_id: "O-123",               # Custom parameter
+  customer_id: "C-456"             # Another custom parameter
+)
+
+# Or queue it for background processing
+OrderProcessingWorkflow.perform_later(
+  "order-123-async",               # Unique workflow key
+  order_id: "O-124",
+  customer_id: "C-457"
+)
+```
+
+**Important:** Workflows must use keyword arguments only, not positional arguments.
+
 #### ⚡ Durable Execution
 
 The `durably_execute` method ensures operations are executed exactly once, even if the job fails and is retried:
@@ -147,13 +197,15 @@ if context.key?(:user_id)
 end
 ```
 
+The context supports serializable Ruby objects (Hash, Array, String, Integer, Float, Boolean, and nil) and validates types automatically.
+
 ### 🛡️ Error Handling
 
 ChronoForge automatically tracks errors and provides configurable retry capabilities:
 
 ```ruby
 class MyWorkflow < ApplicationJob
-  include ChronoForge::Executor
+  prepend ChronoForge::Executor
 
   private
 
@@ -198,14 +250,18 @@ class WorkflowTest < ActiveJob::TestCase
   include ChaoticJob::Helpers
 
   def test_workflow_completion
-    # Enqueue the job
-    OrderProcessingWorkflow.perform_later("order_123")
+    # Enqueue the job with a unique key and custom parameters
+    OrderProcessingWorkflow.perform_later(
+      "order-test-123",
+      order_id: "O-123",
+      customer_id: "C-456"
+    )
     
     # Perform all enqueued jobs
     perform_all_jobs
     
     # Assert workflow completed successfully
-    workflow = ChronoForge::Workflow.last
+    workflow = ChronoForge::Workflow.find_by(key: "order-test-123")
     assert workflow.completed?
     
     # Check workflow context
@@ -232,6 +288,100 @@ ChronoForge is ideal for:
 - **Multi-step workflows** - Onboarding flows, approval processes, multi-stage jobs
 - **State machines with time-based transitions** - Document approval, subscription lifecycle
 
+## 🧠 Advanced State Management
+
+ChronoForge workflows follow a sophisticated state machine model to ensure durability and fault tolerance. Understanding these states and transitions is essential for troubleshooting and recovery.
+
+### Workflow State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> created: Workflow Created
+    created --> idle: Initial State
+    idle --> running: Job Started
+    running --> idle: Waiting
+    running --> completed: All Steps Completed
+    running --> failed: Max Retries Exhausted
+    running --> stalled: Unrecoverable Error
+    idle --> running: Resumed
+    stalled --> [*]: Requires Manual Intervention
+    failed --> [*]: Requires Manual Intervention
+    completed --> [*]: Workflow Succeeded
+```
+
+### State Descriptions
+
+#### Created
+- **Description**: Initial state when a workflow record is first created
+- **Behavior**: Transitions immediately to idle state
+- **Duration**: Momentary
+
+#### Idle
+- **Description**: The workflow is waiting to be processed or between processing steps
+- **Behavior**: Not locked, available to be picked up by job processor
+- **Duration**: Can be minutes to days, depending on wait conditions
+
+#### Running
+- **Description**: The workflow is actively being processed
+- **Identifiers**: Has locked_at and locked_by values set
+- **Behavior**: Protected against concurrent execution
+- **Duration**: Should be brief unless performing long operations
+
+#### Completed
+- **Description**: The workflow has successfully executed all steps
+- **Identifiers**: Has completed_at timestamp, state = "completed"
+- **Behavior**: Final state, no further processing
+- **Typical Exit Points**: All processing completed successfully
+
+#### Failed
+- **Description**: The workflow has failed after exhausting retry attempts
+- **Identifiers**: Has failure-related data in error_logs, state = "failed"
+- **Behavior**: No automatic recovery, requires manual intervention
+- **Typical Exit Points**: Max retries exhausted, explicit failure, non-retryable error
+
+#### Stalled
+- **Description**: The workflow encountered an unrecoverable error but wasn't explicitly failed
+- **Identifiers**: Not completed, not running, has errors in error_logs
+- **Behavior**: Requires manual investigation and intervention
+- **Typical Exit Points**: ExecutionFailedError, unexpected exceptions, system failures
+
+### Handling Different Workflow States
+
+#### Recovering Stalled/Failed Workflows
+
+```ruby
+workflow = ChronoForge::Workflow.find_by(key: "order-123")
+
+if workflow.stalled? || workflow.failed?
+  job_class = workflow.job_class.constantize
+  
+  # Retry immediately
+  job_class.retry_now(workflow.key)
+  
+  # Or retry asynchronously
+  job_class.retry_later(workflow.key)
+end
+```
+
+#### Monitoring Running Workflows
+
+Long-running workflows might indicate issues:
+
+```ruby
+# Find workflows running for too long
+long_running = ChronoForge::Workflow.where(state: :running)
+                                   .where('locked_at < ?', 30.minutes.ago)
+
+long_running.each do |workflow|
+  # Log potential issues for investigation
+  Rails.logger.warn "Workflow #{workflow.key} has been running for >30 minutes"
+  
+  # Optionally force unlock if you suspect deadlock
+  # CAUTION: Only do this if you're certain the job is stuck
+  # workflow.update!(locked_at: nil, locked_by: nil, state: :idle)
+end
+```
+
 ## 🚀 Development
 
 After checking out the repo, run:

data/export.json

@@ -5,7 +5,7 @@
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/README.md",
-    "contents": "# ChronoForge\n\nChronoForge is a Ruby gem that provides a robust framework for building durable, distributed workflows in Ruby on Rails applications. It offers a reliable way to handle long-running processes, state management, and error recovery.\n\n## Features\n\n- **Durable Execution**: Automatically tracks and recovers from failures during workflow execution\n- **State Management**: Built-in workflow state tracking with support for custom contexts\n- **Concurrency Control**: Advanced locking mechanisms to prevent concurrent execution of the same workflow\n- **Error Handling**: Comprehensive error tracking and retry strategies\n- **Execution Logging**: Detailed logging of workflow execution steps and errors\n- **Wait States**: Support for time-based waits and condition-based waiting\n- **Database-Backed**: All workflow state is persisted to the database for durability\n- **ActiveJob Integration**: Seamlessly works with any ActiveJob backend\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'chrono_forge'\n```\n\nThen execute:\n\n```bash\n$ bundle install\n```\n\nOr install it directly:\n\n```bash\n$ gem install chrono_forge\n```\n\nAfter installation, run the generator to create the necessary database migrations:\n\n```bash\n$ rails generate chrono_forge:install\n$ rails db:migrate\n```\n\n## Usage\n\n### Basic Workflow Example\n\nHere's a complete example of a durable order processing workflow:\n\n```ruby\nclass OrderProcessingWorkflow < ApplicationJob\n  include ChronoForge::Executor\n\n  def perform\n    # Context can be used to pass and store data between executions\n    context[\"order_id\"] = SecureRandom.hex\n\n    # Wait until payment is confirmed\n    wait_until :payment_confirmed?\n\n    # Wait for potential fraud check\n    wait 1.minute, :fraud_check_delay\n\n    # Durably execute order processing\n    durably_execute :process_order\n\n    # Final steps\n    complete_order\n  end\n\n  private\n\n  def payment_confirmed?\n    PaymentService.confirmed?(context[\"order_id\"])\n  end\n\n  def process_order\n    context[\"processed_at\"] = Time.current.iso8601\n    OrderProcessor.process(context[\"order_id\"])\n  end\n\n  def complete_order\n    context[\"completed_at\"] = Time.current.iso8601\n    OrderCompletionService.complete(context[\"order_id\"])\n  end\nend\n```\n\n### Workflow Features\n\n#### Durable Execution\n\nThe `durably_execute` method ensures operations are executed exactly once:\n\n```ruby\n# Execute a method\ndurably_execute(:process_payment, max_attempts: 3)\n\n# Or with a block\ndurably_execute -> (ctx) {\n  Payment.process(ctx[:payment_id])\n}\n```\n\n#### Wait States\n\nChronoForge supports both time-based and condition-based waits:\n\n```ruby\n# Wait for a specific duration\nwait 1.hour, :cooling_period\n\n# Wait until a condition is met\nwait_until :payment_processed, \n  timeout: 1.hour,\n  check_interval: 5.minutes\n```\n\n#### Workflow Context\n\nChronoForge provides a persistent context that survives job restarts:\n\n```ruby\n# Set context values\ncontext[:user_name] = \"John Doe\"\ncontext[:status] = \"processing\"\n\n# Read context values\nuser_name = context[:user_name]\n```\n\n### Error Handling\n\nChronoForge automatically tracks errors and provides retry capabilities:\n\n```ruby\nclass MyWorkflow < ApplicationJob\n  include ChronoForge::Executor\n\n  private\n\n  def should_retry?(error, attempt_count)\n    case error\n    when NetworkError\n      attempt_count < 5\n    when ValidationError\n      false  # Don't retry validation errors\n    else\n      attempt_count < 3\n    end\n  end\nend\n```\n\n## Testing\n\nChronoForge is designed to be easily testable using [ChaoticJob](https://github.com/fractaledmind/chaotic_job), a testing framework that makes it simple to test complex job workflows. Here's how to set up your test environment:\n\n1. Add ChaoticJob to your Gemfile's test group:\n\n```ruby\ngroup :test do\n  gem 'chaotic_job'\nend\n```\n\n2. Set up your test helper:\n\n```ruby\n# test_helper.rb\nrequire 'chrono_forge'\nrequire 'minitest/autorun'\nrequire 'chaotic_job'\n```\n\nExample test:\n\n```ruby\nclass WorkflowTest < ActiveJob::TestCase\n  include ChaoticJob::Helpers\n\n  def test_workflow_completion\n    # Enqueue the job\n    OrderProcessingWorkflow.perform_later(\"order_123\")\n    \n    # Perform all enqueued jobs\n    perform_all_jobs\n    \n    # Assert workflow completed successfully\n    workflow = ChronoForge::Workflow.last\n    assert workflow.completed?\n    \n    # Check workflow context\n    assert workflow.context[\"processed_at\"].present?\n    assert workflow.context[\"completed_at\"].present?\n  end\nend\n```\n\nChaoticJob provides several helpful methods for testing workflows:\n\n- `perform_all_jobs`: Processes all enqueued jobs, including those enqueued during job execution\n\nFor testing with specific job processing libraries like Sidekiq or Delayed Job, you can still use their respective testing modes, but ChaoticJob is recommended for testing ChronoForge workflows as it better handles the complexities of nested job scheduling and wait states.\n\n\n## Database Schema\n\nChronoForge creates three main tables:\n\n1. `chrono_forge_workflows`: Stores workflow state and context\n2. `chrono_forge_execution_logs`: Tracks individual execution steps\n3. `chrono_forge_error_logs`: Records detailed error information\n\n## Development\n\nAfter checking out the repo, run:\n\n```bash\n$ bin/setup                 # Install dependencies\n$ bundle exec rake test     # Run the tests\n$ bin/appraise              # Run the full suite of appraisals\n$ bin/console               # Start an interactive console\n```\n\nThe test suite uses SQLite by default and includes:\n- Unit tests for core functionality\n- Integration tests with ActiveJob\n- Example workflow implementations\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin feature/my-new-feature`)\n5. Create a new Pull Request\n\nPlease include tests for any new features or bug fixes.\n\n## License\n\nThis gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n"
+    "contents": "# ChronoForge\n\n![Version](https://img.shields.io/badge/version-0.3.0-blue.svg)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n> A robust framework for building durable, distributed workflows in Ruby on Rails applications\n\nChronoForge provides a powerful solution for handling long-running processes, managing state, and recovering from failures in your Rails applications. Built on top of ActiveJob, it ensures your critical business processes remain resilient and traceable.\n\n## 🌟 Features\n\n- **Durable Execution**: Automatically tracks and recovers from failures during workflow execution\n- **State Management**: Built-in workflow state tracking with persistent context storage\n- **Concurrency Control**: Advanced locking mechanisms to prevent parallel execution of the same workflow\n- **Error Handling**: Comprehensive error tracking with configurable retry strategies\n- **Execution Logging**: Detailed logging of workflow steps and errors for visibility\n- **Wait States**: Support for time-based waits and condition-based waiting\n- **Database-Backed**: All workflow state is persisted to ensure durability\n- **ActiveJob Integration**: Compatible with all ActiveJob backends, though database-backed processors (like Solid Queue) provide the most reliable experience for long-running workflows\n\n## 📦 Installation\n\nAdd to your application's Gemfile:\n\n```ruby\ngem 'chrono_forge'\n```\n\nThen execute:\n\n```bash\n$ bundle install\n```\n\nOr install directly:\n\n```bash\n$ gem install chrono_forge\n```\n\nAfter installation, run the generator to create the necessary database migrations:\n\n```bash\n$ rails generate chrono_forge:install\n$ rails db:migrate\n```\n\n## 📋 Usage\n\n### Creating and Executing Workflows\n\nChronoForge workflows are ActiveJob classes that prepend the `ChronoForge::Executor` module. Each workflow can **only** accept keyword arguments:\n\n```ruby\n# Define your workflow class\nclass OrderProcessingWorkflow < ApplicationJob\n  prepend ChronoForge::Executor\n  \n  def perform(order_id:, customer_id:)\n    # Workflow steps...\n  end\nend\n```\n\nAll workflows require a unique identifier when executed. This identifier is used to track and manage the workflow:\n\n```ruby\n# Execute the workflow\nOrderProcessingWorkflow.perform_later(\n  \"order-123\",                 # Unique workflow key\n  order_id: \"order-134\",       # Custom kwargs\n  customer_id: \"customer-456\"  # More custom kwargs\n)\n```\n\n### Basic Workflow Example\n\nHere's a complete example of a durable order processing workflow:\n\n```ruby\nclass OrderProcessingWorkflow < ApplicationJob\n  prepend ChronoForge::Executor\n\n  def perform(order_id:)\n    @order_id = order_id\n\n    # Context can be used to pass and store data between executions\n    context.set_once \"execution_id\", SecureRandom.hex\n\n    # Wait until payment is confirmed\n    wait_until :payment_confirmed?\n\n    # Wait for potential fraud check\n    wait 1.minute, :fraud_check_delay\n\n    # Durably execute order processing\n    durably_execute :process_order\n\n    # Final steps\n    complete_order\n  end\n\n  private\n\n  def payment_confirmed?\n    PaymentService.confirmed?(@order_id, context[\"execution_id\"])\n  end\n\n  def process_order\n    OrderProcessor.process(@order_id, context[\"execution_id\"])\n    context[\"processed_at\"] = Time.current.iso8601\n  end\n\n  def complete_order\n    OrderCompletionService.complete(@order_id, context[\"execution_id\"])\n    context[\"completed_at\"] = Time.current.iso8601\n  end\nend\n```\n\n### Core Workflow Features\n\n#### 🚀 Executing Workflows\n\nChronoForge workflows are executed through ActiveJob's standard interface with a specific parameter structure:\n\n```ruby\n# Perform the workflow immediately\nOrderProcessingWorkflow.perform_now(\n  \"order-123\",                     # Unique workflow key\n  order_id: \"O-123\",               # Custom parameter\n  customer_id: \"C-456\"             # Another custom parameter\n)\n\n# Or queue it for background processing\nOrderProcessingWorkflow.perform_later(\n  \"order-123-async\",               # Unique workflow key\n  order_id: \"O-124\",\n  customer_id: \"C-457\"\n)\n```\n\n**Important:** Workflows must use keyword arguments only, not positional arguments.\n\n#### ⚡ Durable Execution\n\nThe `durably_execute` method ensures operations are executed exactly once, even if the job fails and is retried:\n\n```ruby\n# Execute a method\ndurably_execute(:process_payment, max_attempts: 3)\n\n# Or with a block\ndurably_execute -> (ctx) {\n  Payment.process(ctx[:payment_id])\n}\n```\n\n#### ⏱️ Wait States\n\nChronoForge supports both time-based and condition-based waits:\n\n```ruby\n# Wait for a specific duration\nwait 1.hour, :cooling_period\n\n# Wait until a condition is met\nwait_until :payment_processed, \n  timeout: 1.hour,\n  check_interval: 5.minutes\n```\n\n#### 🔄 Workflow Context\n\nChronoForge provides a persistent context that survives job restarts. The context behaves like a Hash but with additional capabilities:\n\n```ruby\n# Set context values\ncontext[:user_name] = \"John Doe\"\ncontext[:status] = \"processing\"\n\n# Read context values\nuser_name = context[:user_name]\n\n# Using the fetch method (returns default if key doesn't exist)\nstatus = context.fetch(:status, \"pending\")\n\n# Set a value with the set method (alias for []=)\ncontext.set(:total_amount, 99.99)\n\n# Set a value only if the key doesn't already exist\ncontext.set_once(:created_at, Time.current.iso8601)\n\n# Check if a key exists\nif context.key?(:user_id)\n  # Do something with the user ID\nend\n```\n\nThe context supports serializable Ruby objects (Hash, Array, String, Integer, Float, Boolean, and nil) and validates types automatically.\n\n### 🛡️ Error Handling\n\nChronoForge automatically tracks errors and provides configurable retry capabilities:\n\n```ruby\nclass MyWorkflow < ApplicationJob\n  prepend ChronoForge::Executor\n\n  private\n\n  def should_retry?(error, attempt_count)\n    case error\n    when NetworkError\n      attempt_count < 5  # Retry network errors up to 5 times\n    when ValidationError\n      false  # Don't retry validation errors\n    else\n      attempt_count < 3  # Default retry policy\n    end\n  end\nend\n```\n\n## 🧪 Testing\n\nChronoForge is designed to be easily testable using [ChaoticJob](https://github.com/fractaledmind/chaotic_job), a testing framework that makes it simple to test complex job workflows:\n\n1. Add ChaoticJob to your Gemfile's test group:\n\n```ruby\ngroup :test do\n  gem 'chaotic_job'\nend\n```\n\n2. Set up your test helper:\n\n```ruby\n# test_helper.rb\nrequire 'chrono_forge'\nrequire 'minitest/autorun'\nrequire 'chaotic_job'\n```\n\nExample test:\n\n```ruby\nclass WorkflowTest < ActiveJob::TestCase\n  include ChaoticJob::Helpers\n\n  def test_workflow_completion\n    # Enqueue the job with a unique key and custom parameters\n    OrderProcessingWorkflow.perform_later(\n      \"order-test-123\",\n      order_id: \"O-123\",\n      customer_id: \"C-456\"\n    )\n    \n    # Perform all enqueued jobs\n    perform_all_jobs\n    \n    # Assert workflow completed successfully\n    workflow = ChronoForge::Workflow.find_by(key: \"order-test-123\")\n    assert workflow.completed?\n    \n    # Check workflow context\n    assert workflow.context[\"processed_at\"].present?\n    assert workflow.context[\"completed_at\"].present?\n  end\nend\n```\n\n## 🗄️ Database Schema\n\nChronoForge creates three main tables:\n\n1. **chrono_forge_workflows**: Stores workflow state and context\n2. **chrono_forge_execution_logs**: Tracks individual execution steps\n3. **chrono_forge_error_logs**: Records detailed error information\n\n## 🔍 When to Use ChronoForge\n\nChronoForge is ideal for:\n\n- **Long-running business processes** - Order processing, account registration flows\n- **Processes requiring durability** - Financial transactions, data migrations\n- **Multi-step workflows** - Onboarding flows, approval processes, multi-stage jobs\n- **State machines with time-based transitions** - Document approval, subscription lifecycle\n\n## 🚀 Development\n\nAfter checking out the repo, run:\n\n```bash\n$ bin/setup                 # Install dependencies\n$ bundle exec rake test     # Run the tests\n$ bin/appraise              # Run the full suite of appraisals\n$ bin/console               # Start an interactive console\n```\n\nThe test suite uses SQLite by default and includes:\n- Unit tests for core functionality\n- Integration tests with ActiveJob\n- Example workflow implementations\n\n## 👥 Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin feature/my-new-feature`)\n5. Create a new Pull Request\n\nPlease include tests for any new features or bug fixes.\n\n## 📜 License\n\nThis gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n"
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/chrono_forge.gemspec",
@@ -61,11 +61,11 @@
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/lib/chrono_forge/version.rb",
-    "contents": "# frozen_string_literal: true\n\nmodule ChronoForge\n  VERSION = \"0.2.0\"\nend\n"
+    "contents": "# frozen_string_literal: true\n\nmodule ChronoForge\n  VERSION = \"0.3.1\"\nend\n"
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/lib/chrono_forge/workflow.rb",
-    "contents": "# frozen_string_literal: true\n\n# == Schema Information\n#\n# Table name: chrono_forge_workflows\n#\n#  id           :integer          not null, primary key\n#  completed_at :datetime\n#  context      :json             not null\n#  job_class    :string           not null\n#  key          :string           not null\n#  kwargs       :json             not null\n#  options      :json             not null\n#  locked_at    :datetime\n#  started_at   :datetime\n#  state        :integer          default(\"idle\"), not null\n#  created_at   :datetime         not null\n#  updated_at   :datetime         not null\n#\n# Indexes\n#\n#  index_chrono_forge_workflows_on_key  (key) UNIQUE\n#\nmodule ChronoForge\n  class Workflow < ActiveRecord::Base\n    self.table_name = \"chrono_forge_workflows\"\n\n    has_many :execution_logs, -> { order(id: :asc) }\n    has_many :error_logs, -> { order(id: :asc) }\n\n    enum :state, %i[\n      idle\n      running\n      completed\n      failed\n      stalled\n    ]\n\n    # Serialization for metadata\n    serialize :metadata, coder: JSON\n\n    def executable?\n      idle? || running?\n    end\n\n    def job_klass\n      job_class.constantize\n    end\n  end\nend\n"
+    "contents": "# frozen_string_literal: true\n\n# == Schema Information\n#\n# Table name: chrono_forge_workflows\n#\n#  id           :integer          not null, primary key\n#  completed_at :datetime\n#  context      :json             not null\n#  job_class    :string           not null\n#  key          :string           not null\n#  kwargs       :json             not null\n#  options      :json             not null\n#  locked_at    :datetime\n#  started_at   :datetime\n#  state        :integer          default(\"idle\"), not null\n#  created_at   :datetime         not null\n#  updated_at   :datetime         not null\n#\n# Indexes\n#\n#  index_chrono_forge_workflows_on_key  (key) UNIQUE\n#\nmodule ChronoForge\n  class Workflow < ActiveRecord::Base\n    self.table_name = \"chrono_forge_workflows\"\n\n    has_many :execution_logs, -> { order(id: :asc) }, dependent: :destroy\n    has_many :error_logs, -> { order(id: :asc) }, dependent: :destroy\n\n    enum :state, %i[\n      idle\n      running\n      completed\n      failed\n      stalled\n    ]\n\n    # Serialization for metadata\n    serialize :metadata, coder: JSON\n\n    def executable?\n      idle? || running?\n    end\n\n    def job_klass\n      job_class.constantize\n    end\n  end\nend\n"
   },
   {
     "path": "/Users/stefan/Documents/plutonium/chrono_forge/lib/chrono_forge.rb",

data/lib/chrono_forge/executor/lock_strategy.rb

@@ -22,20 +22,23 @@ module ChronoForge
             state: :running
           )
 
+          Rails.logger.debug { "ChronoForge:#{self.class} job(#{job_id}) acquired lock for workflow(#{workflow.key})" }
+
           workflow
         end
       end
 
-      def self.release_lock(job_id, workflow)
+      def self.release_lock(job_id, workflow, force: false)
         workflow = workflow.reload
-        if workflow.locked_by != job_id
+        if !force && workflow.locked_by != job_id
           raise LongRunningConcurrentExecutionError,
-            "#{self.class}(#{job_id}) executed longer than specified max_duration, " \
-            "allowing another instance(#{workflow.locked_by}) to acquire the lock."
+            "ChronoForge:#{self.class} job(#{job_id}) executed longer than specified max_duration, " \
+            "allowed another instance job(#{workflow.locked_by}) to acquire the lock."
         end
 
         columns = {locked_at: nil, locked_by: nil}
-        columns[:state] = :idle if workflow.running?
+        columns[:state] = :idle if force || workflow.running?
+
 
         workflow.update_columns(columns)
       end

data/lib/chrono_forge/executor/methods/durably_execute.rb

@@ -35,7 +35,7 @@ module ChronoForge
               state: :completed,
               completed_at: Time.current
             )
-            
+
             # return nil
             nil
           rescue HaltExecutionFlow

data/lib/chrono_forge/executor/methods/workflow_states.rb

@@ -0,0 +1,128 @@
+module ChronoForge
+  module Executor
+    module Methods
+      module WorkflowStates
+        private
+        
+        def complete_workflow!
+          # Create an execution log for workflow completion
+          execution_log = ExecutionLog.create_or_find_by!(
+            workflow: workflow,
+            step_name: "$workflow_completion$"
+          ) do |log|
+            log.started_at = Time.current
+          end
+
+          begin
+            execution_log.update!(
+              attempts: execution_log.attempts + 1,
+              last_executed_at: Time.current
+            )
+
+            workflow.completed_at = Time.current
+            workflow.completed!
+
+            # Mark execution log as completed
+            execution_log.update!(
+              state: :completed,
+              completed_at: Time.current
+            )
+
+            # Return the execution log for tracking
+            execution_log
+          rescue => e
+            # Log any errors
+            execution_log.update!(
+              state: :failed,
+              error_message: e.message,
+              error_class: e.class.name
+            )
+            raise
+          end
+        end
+
+        def fail_workflow!(error_log)
+          # Create an execution log for workflow failure
+          execution_log = ExecutionLog.create_or_find_by!(
+            workflow: workflow,
+            step_name: "$workflow_failure$#{error_log.id}"
+          ) do |log|
+            log.started_at = Time.current
+            log.metadata = {
+              error_log_id: error_log.id
+            }
+          end
+
+          begin
+            execution_log.update!(
+              attempts: execution_log.attempts + 1,
+              last_executed_at: Time.current
+            )
+
+            workflow.failed!
+
+            # Mark execution log as completed
+            execution_log.update!(
+              state: :completed,
+              completed_at: Time.current
+            )
+
+            # Return the execution log for tracking
+            execution_log
+          rescue => e
+            # Log any errors
+            execution_log.update!(
+              state: :failed,
+              error_message: e.message,
+              error_class: e.class.name
+            )
+            raise
+          end
+        end
+
+        def retry_workflow!
+          # Check if the workflow is stalled or failed
+          unless workflow.stalled? || workflow.failed?
+            raise WorkflowNotRetryableError, "Cannot retry workflow(#{workflow.key}) in #{workflow.state} state. Only stalled or failed workflows can be retried."
+          end
+
+          # Create an execution log for workflow retry
+          execution_log = ExecutionLog.create!(
+            workflow: workflow,
+            step_name: "$workflow_retry$#{Time.current.to_i}",
+            started_at: Time.current,
+            attempts: 1,
+            last_executed_at: Time.current,
+            metadata: {
+              previous_state: workflow.state,
+              requested_at: Time.current,
+              job_id: job_id
+            }
+          )
+
+          begin
+            # Release any existing locks
+            self.class::LockStrategy.release_lock(job_id, workflow, force: true)
+
+            # Mark execution log as completed
+            execution_log.update!(
+              state: :completed,
+              completed_at: Time.current
+            )
+
+            # Return the execution log for tracking
+            execution_log
+          rescue => e
+            # Log any errors
+            execution_log.update!(
+              state: :failed,
+              error_message: e.message,
+              error_class: e.class.name
+            )
+            raise
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chrono_forge/executor/methods.rb

@@ -4,6 +4,7 @@ module ChronoForge
       include Methods::Wait
       include Methods::WaitUntil
       include Methods::DurablyExecute
+      include Methods::WorkflowStates
     end
   end
 end

data/lib/chrono_forge/executor.rb

@@ -8,24 +8,68 @@ module ChronoForge
 
     class HaltExecutionFlow < ExecutionFlowControl; end
 
+    class NotExecutableError < Error; end
+
+    class WorkflowNotRetryableError < NotExecutableError; end
+
     include Methods
 
-    def perform(key, attempt: 0, options: {}, **kwargs)
+    # Add class methods
+    def self.prepended(base)
+      class << base
+        # Enforce expected signature for perform_now with key as first arg and keywords after
+        def perform_now(key, **kwargs)
+          if !key.is_a?(String)
+            raise ArgumentError, "Workflow key must be a string as the first argument"
+          end
+          super(key, **kwargs)
+        end
+        
+        # Enforce expected signature for perform_later with key as first arg and keywords after
+        def perform_later(key, **kwargs)
+          if !key.is_a?(String)
+            raise ArgumentError, "Workflow key must be a string as the first argument"
+          end
+          super(key, **kwargs)
+        end
+        
+        # Add retry_now class method that calls perform_now with retry_workflow: true
+        def retry_now(key, **kwargs)
+          perform_now(key, retry_workflow: true, **kwargs)
+        end
+        
+        # Add retry_later class method that calls perform_later with retry_workflow: true
+        def retry_later(key, **kwargs)
+          perform_later(key, retry_workflow: true, **kwargs)
+        end
+      end
+    end
+
+    def perform(key, attempt: 0, retry_workflow: false, options: {}, **kwargs)
       # Prevent excessive retries
       if attempt >= self.class::RetryStrategy.max_attempts
-        Rails.logger.error { "Max attempts reached for job #{key}" }
+        Rails.logger.error { "ChronoForge:#{self.class} max attempts reached for job workflow(#{key})" }
         return
       end
 
       # Find or create job with comprehensive tracking
       setup_workflow(key, options, kwargs)
 
+      # Handle retry parameter - unlock and continue execution
+      retry_workflow! if retry_workflow
+
+      # Track if we acquired the lock
+      lock_acquired = false
+
       begin
-        # Skip if workflow cannot be executed
-        return unless workflow.executable?
+        # Raise error if workflow cannot be executed
+        unless workflow.executable?
+          raise NotExecutableError, "#{self.class}(#{key}) is not in an executable state"
+        end
 
         # Acquire lock with advanced concurrency protection
-        self.class::LockStrategy.acquire_lock(job_id, workflow, max_duration: max_duration)
+        @workflow = self.class::LockStrategy.acquire_lock(job_id, workflow, max_duration: max_duration)
+        lock_acquired = true
 
         # Execute core job logic
         super(**workflow.kwargs.symbolize_keys)
@@ -33,20 +77,22 @@ module ChronoForge
         # Mark as complete
         complete_workflow!
       rescue ExecutionFailedError => e
-        Rails.logger.error { "Execution step failed for #{key}" }
+        Rails.logger.error { "ChronoForge:#{self.class} execution step failed for workflow(#{key})" }
         self.class::ExecutionTracker.track_error(workflow, e)
         workflow.stalled!
         nil
       rescue HaltExecutionFlow
         # Halt execution
-        Rails.logger.debug { "Execution halted for #{key}" }
+        Rails.logger.debug { "ChronoForge:#{self.class} execution halted for workflow(#{key})" }
         nil
       rescue ConcurrentExecutionError
         # Graceful handling of concurrent execution
-        Rails.logger.warn { "Concurrent execution detected for job #{key}" }
+        Rails.logger.warn { "ChronoForge:#{self.class} concurrent execution detected for job #{key}" }
         nil
+      rescue NotExecutableError
+        raise
       rescue => e
-        Rails.logger.error { "An error occurred during execution of #{key}" }
+        Rails.logger.error { "ChronoForge:#{self.class} an error occurred during execution of workflow(#{key})" }
         error_log = self.class::ExecutionTracker.track_error(workflow, e)
 
         # Retry if applicable
@@ -56,90 +102,16 @@ module ChronoForge
           fail_workflow! error_log
         end
       ensure
-        context.save!
-        # Always release the lock
-        self.class::LockStrategy.release_lock(job_id, workflow)
+        # Only release lock if we acquired it
+        if lock_acquired
+          context.save!
+          self.class::LockStrategy.release_lock(job_id, workflow)
+        end
       end
     end
 
     private
 
-    def complete_workflow!
-      # Create an execution log for workflow completion
-      execution_log = ExecutionLog.create_or_find_by!(
-        workflow: workflow,
-        step_name: "$workflow_completion$"
-      ) do |log|
-        log.started_at = Time.current
-      end
-
-      begin
-        execution_log.update!(
-          attempts: execution_log.attempts + 1,
-          last_executed_at: Time.current
-        )
-
-        workflow.completed_at = Time.current
-        workflow.completed!
-
-        # Mark execution log as completed
-        execution_log.update!(
-          state: :completed,
-          completed_at: Time.current
-        )
-
-        # Return the execution log for tracking
-        execution_log
-      rescue => e
-        # Log any completion errors
-        execution_log.update!(
-          state: :failed,
-          error_message: e.message,
-          error_class: e.class.name
-        )
-        raise
-      end
-    end
-
-    def fail_workflow!(error_log)
-      # Create an execution log for workflow failure
-      execution_log = ExecutionLog.create_or_find_by!(
-        workflow: workflow,
-        step_name: "$workflow_failure$"
-      ) do |log|
-        log.started_at = Time.current
-        log.metadata = {
-          error_log_id: error_log.id
-        }
-      end
-
-      begin
-        execution_log.update!(
-          attempts: execution_log.attempts + 1,
-          last_executed_at: Time.current
-        )
-
-        workflow.failed!
-
-        # Mark execution log as completed
-        execution_log.update!(
-          state: :completed,
-          completed_at: Time.current
-        )
-
-        # Return the execution log for tracking
-        execution_log
-      rescue => e
-        # Log any completion errors
-        execution_log.update!(
-          state: :failed,
-          error_message: e.message,
-          error_class: e.class.name
-        )
-        raise
-      end
-    end
-
     def setup_workflow(key, options, kwargs)
       @workflow = find_workflow(key, options, kwargs)
       @context = Context.new(@workflow)

data/lib/chrono_forge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChronoForge
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/chrono_forge/workflow.rb

@@ -25,8 +25,8 @@ module ChronoForge
   class Workflow < ActiveRecord::Base
     self.table_name = "chrono_forge_workflows"
 
-    has_many :execution_logs, -> { order(id: :asc) }
-    has_many :error_logs, -> { order(id: :asc) }
+    has_many :execution_logs, -> { order(id: :asc) }, dependent: :destroy
+    has_many :error_logs, -> { order(id: :asc) }, dependent: :destroy
 
     enum :state, %i[
       idle

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chrono_forge
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-28 00:00:00.000000000 Z
+date: 2025-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -196,6 +196,7 @@ files:
 - lib/chrono_forge/executor/methods/durably_execute.rb
 - lib/chrono_forge/executor/methods/wait.rb
 - lib/chrono_forge/executor/methods/wait_until.rb
+- lib/chrono_forge/executor/methods/workflow_states.rb
 - lib/chrono_forge/executor/retry_strategy.rb
 - lib/chrono_forge/version.rb
 - lib/chrono_forge/workflow.rb