chrono_forge 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 518b82abfe5b0061b385b4293ae955eb6a188c1e3bf76f4763e5f03e13359771
-  data.tar.gz: ca59809649371db8eaa1e6eb8579f7bc34d5471f19f065e908b9585b9fb0e2fb
+  metadata.gz: 1d7b16cc9e00eb7cc95b21a13331c9bc2dffdfcbd4f4e060c03e876f261fa73c
+  data.tar.gz: 4f9b0b28f7f69f518898ffc1e591087096ac71d84547d4c185c07cc6f0a11643
 SHA512:
-  metadata.gz: ae7de522ddbaa15625fa38109a63e28167b1831e635e78d95f2f9c0e9d6ff8117418a972dfbeda1555f2059c4d33b5faa286bbd1a07132c6a157c71f3194839d
-  data.tar.gz: ee9a38551628d68e0efb02ad0b4d6f42d97fec92d776e8a394a64c5b05efcac9608cd9f0bb6897b43c8195b31a17e1cb9fb475e44b67a69cda94e898fc59f7f7
+  metadata.gz: 208180ae5d6fbe4b3ad30b05f1a60eb231f9bd3135304211ff7861f50e546eb32815ab5e8307e9c910cd1c5a7bdf951777635304ed7c629a7a62f8740df21c85
+  data.tar.gz: e3fac31dc46d1b126e8de982b02fe70d37ac7ffd6233ec643f20f93296237029640e67bb004cfaf7e71d5f60429cbc4702d4efe40951c48915e3bc08e561ec51

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 ## [Unreleased]
 
+## [0.9.0] - 2026-06-03
+
+### Added
+
+- `ChronoForge::Cleanup` and `ChronoForge::CleanupJob` — a schedulable, batched cleanup that deletes old terminal (completed/failed) workflows and their logs, and (opt-in) prunes the unbounded repetition logs that long-lived `durably_repeat` tasks accumulate. Repetition pruning is frontier-safe: only terminal repetitions scheduled strictly before the coordination log's `last_execution_at` are removed, so catch-up is never disrupted. Retention is configurable per terminal state (`completed_older_than` / `failed_older_than`).
+- `chrono_forge:upgrade` generator that installs additive migrations existing apps are missing (idempotent — re-running either generator skips migrations that already exist).
+- Composite `[state, completed_at]` index on `chrono_forge_workflows` (separate, strong_migrations-safe migration: built `CONCURRENTLY` on PostgreSQL, `if_not_exists`) to keep monitoring and cleanup scans efficient.
+- Validation of user-supplied step names: a name/method/condition containing the reserved `$` separator now raises `ChronoForge::Executor::InvalidStepName`.
+- `step_name` and `attempt` columns on `chrono_forge_error_logs` (additive migration), populated by error tracking so each error is attributable to the step and attempt it came from and can be ordered/correlated when tailing a workflow.
+- Record-level re-execution: `ChronoForge::Workflow#retry_now` / `#retry_later` (plus `#retryable?`), so a failed/stalled workflow can be re-run straight from its record (e.g. `ChronoForge::Workflow.failed.find_each(&:retry_later)`) without constantizing the job class or re-passing the key. `retry_later` validates retryability up front and raises `WorkflowNotRetryableError` immediately instead of enqueuing a job that would fail in the worker.
+
+### Changed
+
+- **Performance:** execution-log and workflow lookups are now SELECT-first instead of INSERT-first, eliminating an `INSERT`-that-fails-on-the-unique-index (plus a burned sequence value) for every already-completed step on every replay.
+- **Performance:** `LockStrategy.release_lock` reads only the lock owner column instead of reloading the full workflow row (which dragged the large JSON `context`/`kwargs`/`options` into memory on every resume).
+- **Performance:** workflow completion/failure persist their execution log in a single `UPDATE` instead of two.
+- **Performance:** `Context` deep-copies values via `as_json` instead of a `JSON.parse(JSON.generate(...))` round-trip.
+- Error-log context snapshots are now bounded: all keys are kept, but once a 64 KB total budget is reached the remaining values are replaced with an `<<omitted>>` marker, so repeated error logging no longer duplicates large context blobs.
+- Workflow retention is measured from when a workflow became terminal (`completed_at` for completed, `updated_at` for failed), not from `created_at` — long-running workflows that only just finished are retained for the full window.
+
+### Breaking
+
+- The per-value `Context` size limit is reduced from 64 KB to **16 KB** and is now measured in **bytes** (previously characters, and `String`-only). `Hash` and `Array` values are now size-validated too. Context is intended for small working state; store large payloads elsewhere and keep a reference. Existing workflows that *write* values larger than 16 KB will raise `ChronoForge::Executor::Context::ValidationError`; already-stored values are unaffected when read.
+
+### Fixed
+
+- A failed step no longer logs its terminal failure twice. Previously the step logged the underlying error and `perform` re-logged the `ExecutionFailedError` control-flow wrapper, producing a duplicate row. The wrapper is no longer logged; `wait_until` timeouts (which had no step-level log) are now logged at the step instead.
+
+### Removed
+
+- Dead `serialize :metadata` declaration on `ChronoForge::Workflow` (the table has no `metadata` column).
+
+### Upgrading
+
+```bash
+rails generate chrono_forge:upgrade
+rails db:migrate
+```
+
 ## [0.1.0] - 2024-12-21
 
 - Initial release

data/README.md

@@ -19,6 +19,7 @@ ChronoForge provides a powerful solution for handling long-running processes, ma
 - **Wait States**: Support for time-based waits and condition-based waiting
 - **Database-Backed**: All workflow state is persisted to ensure durability
 - **ActiveJob Integration**: Compatible with all ActiveJob backends, though database-backed processors (like Solid Queue) provide the most reliable experience for long-running workflows
+- **Retention & Cleanup**: A schedulable job to prune finished workflows and the unbounded logs that periodic tasks accumulate (see [Cleanup & Retention](#-cleanup--retention))
 
 ## 📦 Installation
 
@@ -47,6 +48,21 @@ $ rails generate chrono_forge:install
 $ rails db:migrate
 ```
 
+### Upgrading
+
+When upgrading ChronoForge in an application that was installed with an earlier
+version, run the upgrade generator to pick up any additive schema changes, then
+migrate:
+
+```bash
+$ rails generate chrono_forge:upgrade
+$ rails db:migrate
+```
+
+The upgrade migration is idempotent (`if_not_exists`), so it is safe to run even
+if your schema already has the index. Fresh installs get the index from the
+install migration and do **not** need to run the upgrade.
+
 ## 📋 Usage
 
 ### Creating and Executing Workflows
@@ -431,6 +447,18 @@ end
 
 The context supports serializable Ruby objects (Hash, Array, String, Integer, Float, Boolean, and nil) and validates types automatically.
 
+Hash and Array values are stored as JSON, which has no symbols — so **symbol keys inside a stored hash come back as strings**:
+
+```ruby
+context[:totals] = { paid: 5, pending: 2 }
+context[:totals]          # => { "paid" => 5, "pending" => 2 }
+context[:totals]["paid"]  # => 5   (not context[:totals][:paid])
+```
+
+(The top-level context key itself is interchangeable — `context[:totals]` and `context["totals"]` refer to the same entry.)
+
+Context is meant for **small working state** — ids, flags, timestamps, and small structures used to coordinate steps. Each value is capped at **16 KB** (a `ChronoForge::Executor::Context::ValidationError` is raised above that). Store large payloads (documents, uploads, API responses) in their own storage and keep just a reference (an id or key) in the context.
+
 ### 🛡️ Error Handling
 
 ChronoForge automatically tracks errors and provides configurable retry capabilities:
@@ -581,20 +609,32 @@ stateDiagram-v2
 
 #### Recovering Stalled/Failed Workflows
 
+Re-execute a failed or stalled workflow directly from its record — no need to
+constantize the job class or re-pass the key. Execution resumes via replay, so
+completed steps are skipped and it picks up at the step that failed:
+
 ```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
+workflow.retry_later   # re-run asynchronously (the common case)
+workflow.retry_now     # re-run inline (console/debugging)
 ```
 
+Only `stalled` or `failed` workflows are retryable. `retryable?` lets you check
+first, and both methods **validate up front** — calling `retry_later`
+on a non-retryable workflow raises `ChronoForge::Executor::WorkflowNotRetryableError`
+immediately rather than enqueuing a job that would fail in the worker:
+
+```ruby
+workflow.retryable?   # => true/false
+
+# Bulk re-run everything that failed:
+ChronoForge::Workflow.failed.find_each(&:retry_later)
+```
+
+The class-level form (`MyWorkflow.retry_now(key)` / `retry_later(key)`) still
+works if you have the class and key rather than the record.
+
 #### Monitoring Running Workflows
 
 Long-running workflows might indicate issues:
@@ -614,6 +654,78 @@ long_running.each do |workflow|
 end
 ```
 
+## 🧹 Cleanup & Retention
+
+ChronoForge keeps every workflow and execution-log row indefinitely so that
+replays remain idempotent. Over time two things grow without bound:
+
+1. **Terminal workflows** (`completed` / `failed`) that are no longer needed.
+2. **`durably_repeat` repetition logs** — one row per scheduled execution. A
+   long-lived periodic workflow never reaches a terminal state, so its
+   repetition logs accumulate indefinitely. Past repetitions (those behind the
+   task's current frontier) are never read again, since each resume recomputes
+   the next execution from the coordination log — so they are safe to prune (see
+   the safety note below).
+
+`ChronoForge::Cleanup` reclaims both. It is **not** run automatically — schedule
+it from your own scheduler so you stay in control of retention:
+
+```ruby
+ChronoForge::Cleanup.run(
+  older_than: 90.days,                       # default retention for terminal workflows (+ cascades their logs)
+  completed_older_than: 30.days,             # optional: retention for completed workflows (defaults to older_than)
+  failed_older_than: 180.days,               # optional: keep failures longer for debugging (defaults to older_than)
+  prune_repetition_logs_older_than: 30.days, # opt-in: prune old durably_repeat logs from still-active workflows
+  batch_size: 1_000                          # rows deleted per batch
+)
+# => { workflows: 12, execution_logs: 84, error_logs: 3, repetition_logs: 240 }
+```
+
+Notes:
+
+- `running`, `idle`, and `stalled` workflows are **never** deleted.
+- `completed_older_than` / `failed_older_than` let you keep failed workflows
+  around longer than completed ones; both default to `older_than`.
+- `prune_repetition_logs_older_than` is opt-in (defaults to `nil`); when unset,
+  repetition logs are only removed as part of deleting their parent workflow.
+  Pruning is deliberately conservative: it only removes terminal repetition logs
+  that are both older than the window **and** scheduled strictly before the
+  periodic task's current frontier (the coordination log's `last_execution_at`).
+  Anything at or after the frontier is kept so `durably_repeat`'s catch-up
+  mechanism is never disrupted — so the window is purely a retention preference
+  and is safe even for yearly schedules.
+- Workflow retention is measured from when a workflow became terminal, not when
+  it was created — a long-running workflow that only just finished is kept for
+  the full window. Completed workflows use `completed_at` (immutable); failed
+  workflows use `updated_at` (they have no `completed_at`).
+- The composite `[state, completed_at]` index added in this version keeps these
+  scans efficient — run `chrono_forge:upgrade` if you installed an earlier
+  version.
+
+A ready-made job is bundled so you can schedule it with any recurring-job
+mechanism (Solid Queue recurring tasks, sidekiq-cron, GoodJob cron, the
+`whenever` gem, ...):
+
+```ruby
+ChronoForge::CleanupJob.perform_later(
+  older_than_days: 90,
+  failed_older_than_days: 180,
+  prune_repetition_logs_older_than_days: 30
+)
+```
+
+The job takes plain day counts (not `Duration` objects) so it can be driven from
+a config file. For example, with Solid Queue's recurring tasks
+(`config/recurring.yml`):
+
+```yaml
+production:
+  chrono_forge_cleanup:
+    class: ChronoForge::CleanupJob
+    args: { older_than_days: 90, prune_repetition_logs_older_than_days: 30 }
+    schedule: every day at 3am
+```
+
 ## 🚀 Development
 
 After checking out the repo, run:

data/lib/chrono_forge/cleanup.rb

@@ -0,0 +1,154 @@
+module ChronoForge
+  # Reclaims storage from finished workflows and the unbounded execution-log
+  # rows that periodic tasks (durably_repeat) accumulate.
+  #
+  # ChronoForge keeps every workflow and execution-log row indefinitely so that
+  # replays stay idempotent. Two things grow without bound over time:
+  #
+  #   1. Terminal workflows (completed/failed) that are no longer needed.
+  #   2. durably_repeat repetition logs — one row per scheduled execution. A
+  #      long-lived periodic workflow never reaches a terminal state, so its
+  #      repetition logs accumulate forever.
+  #
+  # This is not run automatically — schedule it from your own scheduler (cron,
+  # Solid Queue recurring tasks, sidekiq-cron, GoodJob cron, the `whenever`
+  # gem, ...). See ChronoForge::CleanupJob for a ready-made job, e.g.:
+  #
+  #   ChronoForge::Cleanup.run(
+  #     older_than: 90.days,                       # default retention for terminal workflows
+  #     failed_older_than: 180.days,               # keep failures longer for debugging
+  #     prune_repetition_logs_older_than: 30.days  # opt in to periodic-log pruning
+  #   )
+  #
+  # == Workflow retention is measured from when a workflow became terminal
+  #
+  # Retention is measured from the terminal transition, not created_at: a
+  # long-running workflow may have been created long ago but only just finished.
+  # Completed workflows use the immutable completed_at; failed workflows have no
+  # completed_at, so they use updated_at (the failed! transition, after which
+  # nothing touches the row — release_lock/context use update_columns/
+  # update_column, which do not bump it).
+  #
+  # == Repetition-log pruning safety
+  #
+  # Pruning periodic logs is opt-in and deliberately conservative. A repetition
+  # log is removed only when its scheduled time is BOTH older than the retention
+  # window AND strictly before the periodic task's current frontier (the
+  # coordination log's last_execution_at). Everything at or after the frontier is
+  # kept, because durably_repeat's catch-up mechanism may still need it: the next
+  # execution is computed as last_execution_at + every, so anything at/after the
+  # frontier can still be revisited, while anything strictly before it never is.
+  # Both checks use the scheduled time embedded in the step name rather than
+  # created_at, which is misleading for catch-up rows created long after the
+  # occurrence they represent. A task that has not executed yet (no frontier) is
+  # never pruned.
+  class Cleanup
+    DEFAULT_RETENTION = 90.days
+    DEFAULT_BATCH_SIZE = 1_000
+    TERMINAL_LOG_STATES = %i[completed failed].freeze
+
+    # @param older_than [ActiveSupport::Duration] default retention for terminal
+    #   workflows; used for any state without a specific override.
+    # @param completed_older_than [ActiveSupport::Duration, nil] retention for
+    #   completed workflows. Defaults to older_than.
+    # @param failed_older_than [ActiveSupport::Duration, nil] retention for
+    #   failed workflows. Defaults to older_than.
+    # @param prune_repetition_logs_older_than [ActiveSupport::Duration, nil]
+    #   when set, also prune old terminal durably_repeat repetition logs from
+    #   still-active workflows (see safety notes above). nil disables it.
+    # @param batch_size [Integer] rows per delete batch.
+    # @return [Hash] counts of deleted rows by category.
+    def self.run(**)
+      new(**).run
+    end
+
+    def initialize(older_than: DEFAULT_RETENTION, completed_older_than: nil, failed_older_than: nil,
+      prune_repetition_logs_older_than: nil, batch_size: DEFAULT_BATCH_SIZE)
+      @completed_older_than = completed_older_than || older_than
+      @failed_older_than = failed_older_than || older_than
+      @prune_repetition_logs_older_than = prune_repetition_logs_older_than
+      @batch_size = batch_size
+    end
+
+    def run
+      result = {workflows: 0, execution_logs: 0, error_logs: 0, repetition_logs: 0}
+
+      # Completed workflows use the immutable completed_at; failed workflows
+      # have no completed_at, so they fall back to updated_at.
+      delete_terminal_workflows(:completed, :completed_at, @completed_older_than, result)
+      delete_terminal_workflows(:failed, :updated_at, @failed_older_than, result)
+      prune_repetition_logs(result) if @prune_repetition_logs_older_than
+
+      result
+    end
+
+    private
+
+    def delete_terminal_workflows(state, timestamp_column, older_than, result)
+      cutoff = older_than.ago
+
+      Workflow.where(state: state)
+        .where(timestamp_column => ..cutoff)
+        .in_batches(of: @batch_size) do |batch|
+        ids = batch.ids
+        next if ids.empty?
+
+        # Delete dependent rows in bulk rather than relying on row-by-row
+        # dependent: :destroy callbacks.
+        result[:execution_logs] += ExecutionLog.where(workflow_id: ids).delete_all
+        result[:error_logs] += ErrorLog.where(workflow_id: ids).delete_all
+        result[:workflows] += Workflow.where(id: ids).delete_all
+      end
+    end
+
+    def prune_repetition_logs(result)
+      cutoff = @prune_repetition_logs_older_than.ago.to_i
+
+      coordination_logs.find_each do |coordination_log|
+        frontier = coordination_frontier(coordination_log)
+        next unless frontier
+
+        # Repetition logs are "<coordination step_name>$<scheduled_at_unix>".
+        # Match the prefix exactly in Ruby rather than via SQL LIKE: the step
+        # name contains "_", a LIKE wildcard, so a LIKE pattern would need
+        # escaping that is not portable across adapters.
+        prefix = "#{coordination_log.step_name}$"
+
+        # Scan in batches so a periodic workflow with a large backlog of
+        # repetition logs (exactly the case cleanup exists to fix) never loads
+        # them all into memory at once. Batching by primary key and only
+        # deleting rows within the current batch keeps the cursor valid.
+        ExecutionLog
+          .where(workflow_id: coordination_log.workflow_id, state: TERMINAL_LOG_STATES)
+          .in_batches(of: @batch_size) do |batch|
+          prunable_ids = batch.pluck(:id, :step_name).filter_map do |id, step_name|
+            next unless step_name.start_with?(prefix)
+
+            scheduled_at = step_name.delete_prefix(prefix).to_i
+            id if scheduled_at < frontier && scheduled_at < cutoff
+          end
+
+          result[:repetition_logs] += ExecutionLog.where(id: prunable_ids).delete_all if prunable_ids.any?
+        end
+      end
+    end
+
+    # Coordination logs are "durably_repeat$<name>" — exactly one "$" segment
+    # after the prefix. Repetition logs add a second "$<timestamp>" segment.
+    def coordination_logs
+      ExecutionLog
+        .where("step_name LIKE ?", "durably_repeat$%")
+        .where.not("step_name LIKE ?", "durably_repeat$%$%")
+        .order(:id)
+    end
+
+    def coordination_frontier(coordination_log)
+      last_execution_at = coordination_log.metadata && coordination_log.metadata["last_execution_at"]
+      return unless last_execution_at
+
+      Time.parse(last_execution_at).to_i
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+end

data/lib/chrono_forge/cleanup_job.rb

@@ -0,0 +1,30 @@
+module ChronoForge
+  # ActiveJob wrapper around {Cleanup} so the cleanup can be enqueued and
+  # scheduled with any recurring-job mechanism (Solid Queue recurring tasks,
+  # sidekiq-cron, GoodJob cron, ...).
+  #
+  # Arguments are plain scalars (day counts) rather than ActiveSupport::Duration
+  # objects so the job can be configured from YAML/cron config files, which can
+  # only carry primitive values:
+  #
+  #   ChronoForge::CleanupJob.perform_later(
+  #     older_than_days: 90,
+  #     failed_older_than_days: 180,
+  #     prune_repetition_logs_older_than_days: 30
+  #   )
+  class CleanupJob < ActiveJob::Base
+    def perform(older_than_days: nil, completed_older_than_days: nil, failed_older_than_days: nil,
+      prune_repetition_logs_older_than_days: nil, batch_size: nil)
+      options = {}
+      options[:older_than] = older_than_days.to_i.days if older_than_days
+      options[:completed_older_than] = completed_older_than_days.to_i.days if completed_older_than_days
+      options[:failed_older_than] = failed_older_than_days.to_i.days if failed_older_than_days
+      if prune_repetition_logs_older_than_days
+        options[:prune_repetition_logs_older_than] = prune_repetition_logs_older_than_days.to_i.days
+      end
+      options[:batch_size] = batch_size.to_i if batch_size
+
+      Cleanup.run(**options)
+    end
+  end
+end

data/lib/chrono_forge/error_log.rb

@@ -5,10 +5,12 @@
 # Table name: chrono_forge_error_logs
 #
 #  id            :integer          not null, primary key
+#  attempt       :integer
 #  backtrace     :text
 #  context       :json
 #  error_class   :string
 #  error_message :text
+#  step_name     :string
 #  created_at    :datetime         not null
 #  updated_at    :datetime         not null
 #  workflow_id   :integer          not null

data/lib/chrono_forge/executor/context.rb

@@ -14,6 +14,17 @@ module ChronoForge
         Array
       ]
 
+      # Maximum serialized byte size of a single context value. Applies to the
+      # variable-length types (String, Hash, Array); scalars are unbounded in
+      # practice. Measured in bytes (not characters) since that is what is
+      # actually stored and what matters for write/storage cost.
+      #
+      # Context is meant to hold small working state (ids, flags, timestamps,
+      # small structures) — not documents or payloads, which belong in their own
+      # storage and can be referenced from context by id. 16 KB per value is
+      # already generous for that (hundreds of ids / dozens of records).
+      MAX_VALUE_BYTESIZE = 16.kilobytes
+
       def initialize(workflow)
         @workflow = workflow
         @context = workflow.context || {}
@@ -67,7 +78,11 @@ module ChronoForge
 
         @context[key.to_s] =
           if value.is_a?(Hash) || value.is_a?(Array)
-            deep_dup(value)
+            # as_json returns a fresh JSON-compatible structure with string keys
+            # — the same normalization the JSON column would apply on save and a
+            # deep copy that protects the store from later mutation of the
+            # source — without the cost of serializing to a string and reparsing.
+            value.as_json
           else
             value
           end
@@ -84,16 +99,19 @@ module ChronoForge
           raise ValidationError, "Unsupported context value type: #{value.inspect}"
         end
 
-        # Optional: Add size constraints
-        if value.is_a?(String) && value.size > 64.kilobytes
-          raise ValidationError, "Context value too large"
+        byte_size = value_byte_size(value)
+        if byte_size && byte_size > MAX_VALUE_BYTESIZE
+          raise ValidationError, "Context value too large (#{byte_size} bytes, max #{MAX_VALUE_BYTESIZE})"
         end
       end
 
-      def deep_dup(obj)
-        JSON.parse(JSON.generate(obj))
-      rescue
-        obj.dup
+      # Serialized byte size for the variable-length types; nil for scalars,
+      # which need no size constraint.
+      def value_byte_size(value)
+        case value
+        when String then value.bytesize
+        when Hash, Array then value.to_json.bytesize
+        end
       end
     end
   end

data/lib/chrono_forge/executor/execution_tracker.rb

@@ -1,16 +1,55 @@
 module ChronoForge
   module Executor
     class ExecutionTracker
-      def self.track_error(workflow, error)
-        # Create a detailed error log
+      # Total budget for the context snapshot copied into each error log.
+      # Transient errors can be logged repeatedly (one row per retry), and the
+      # full context always remains on the workflow itself, so the error copy
+      # only needs to be a bounded diagnostic breadcrumb. Keys are preserved;
+      # values are kept until the running total would exceed this budget, after
+      # which each remaining value is replaced by OMITTED_VALUE. Per-value size
+      # is already bounded by Context validation, so no per-value truncation is
+      # needed here — a single value larger than the budget is simply replaced.
+      MAX_CONTEXT_BYTESIZE = 64.kilobytes
+
+      # Placeholder stored in place of a value that didn't fit the budget.
+      OMITTED_VALUE = "<<omitted>>"
+
+      # @param execution_log [ExecutionLog, nil] the step the error occurred in,
+      #   if any. Its step_name and attempt count are recorded on the error log
+      #   so errors can be attributed to a step and ordered within the workflow.
+      # @param attempt [Integer, nil] explicit attempt number for errors not tied
+      #   to a step (e.g. a workflow-level failure). Falls back to the execution
+      #   log's attempt count.
+      def self.track_error(workflow, error, execution_log: nil, attempt: nil)
         ErrorLog.create!(
           workflow: workflow,
+          step_name: execution_log&.step_name,
+          attempt: attempt || execution_log&.attempts,
           error_class: error.class.name,
           error_message: error.message,
-          backtrace: error.backtrace.join("\n"),
-          context: workflow.context
+          backtrace: error.backtrace&.join("\n"),
+          context: error_context(workflow.context)
         )
       end
+
+      def self.error_context(context)
+        remaining = MAX_CONTEXT_BYTESIZE
+
+        context.each_with_object({}) do |(key, value), kept|
+          size = value.to_json.bytesize
+          if size <= remaining
+            kept[key] = value
+            remaining -= size
+          else
+            kept[key] = OMITTED_VALUE
+          end
+        end
+      rescue
+        # If the context cannot be traversed/serialized, fail safe to a marker
+        # rather than risk persisting something unbounded or unserializable.
+        {"_truncated" => true}
+      end
+      private_class_method :error_context
     end
   end
 end

data/lib/chrono_forge/executor/lock_strategy.rb

@@ -34,11 +34,17 @@ module ChronoForge
         end
 
         def release_lock(job_id, workflow, force: false)
-          workflow = workflow.reload
-          if !force && workflow.locked_by != job_id
+          # Read only the lock owner from the DB rather than reloading the whole
+          # row (which would drag the heavy context/kwargs/options JSON into memory
+          # on every resume) just to verify ownership. The in-memory state is
+          # already accurate here: acquire_lock set it to :running, and a
+          # completed/failed workflow had its state updated on this same instance.
+          current_locked_by = workflow.class.where(id: workflow.id).pick(:locked_by)
+
+          if !force && current_locked_by != job_id
             raise LongRunningConcurrentExecutionError,
               "ChronoForge:#{self.class}(#{workflow.key}) job(#{job_id}) executed longer than specified max_duration, " \
-              "allowed job(#{workflow.locked_by}) to acquire the lock."
+              "allowed job(#{current_locked_by}) to acquire the lock."
           end
 
           columns = {locked_at: nil, locked_by: nil}

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

@@ -96,13 +96,11 @@ module ChronoForge
         # - User actions or form submissions
         #
         def continue_if(condition, name: nil)
+          validate_step_name_segment!(name || condition)
           step_name = "continue_if$#{name || condition}"
 
           # Find or create execution log
-          execution_log = ExecutionLog.create_or_find_by!(
-            workflow: @workflow,
-            step_name: step_name
-          ) do |log|
+          execution_log = find_or_create_execution_log!(step_name) do |log|
             log.started_at = Time.current
             log.metadata = {
               condition: condition.to_s,
@@ -128,7 +126,7 @@ module ChronoForge
           rescue => e
             # Log the error and fail the execution
             Rails.logger.error { "Error evaluating condition #{condition}: #{e.message}" }
-            self.class::ExecutionTracker.track_error(workflow, e)
+            self.class::ExecutionTracker.track_error(workflow, e, execution_log: execution_log)
 
             execution_log.update!(
               state: :failed,

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

@@ -60,12 +60,10 @@ module ChronoForge
         # - Enables monitoring and debugging of execution history
         #
         def durably_execute(method, max_attempts: 3, name: nil)
+          validate_step_name_segment!(name || method)
           step_name = "durably_execute$#{name || method}"
           # Find or create execution log
-          execution_log = ExecutionLog.create_or_find_by!(
-            workflow: @workflow,
-            step_name: step_name
-          ) do |log|
+          execution_log = find_or_create_execution_log!(step_name) do |log|
             log.started_at = Time.current
           end
 
@@ -96,7 +94,7 @@ module ChronoForge
           rescue => e
             # Log the error
             Rails.logger.error { "Error while durably executing #{method}: #{e.message}" }
-            self.class::ExecutionTracker.track_error(workflow, e)
+            self.class::ExecutionTracker.track_error(workflow, e, execution_log: execution_log)
 
             # Optional retry logic
             if execution_log.attempts < max_attempts

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

@@ -101,13 +101,11 @@ module ChronoForge
         # - Repetition logs: `durably_repeat$#{name}$#{timestamp}` - tracks individual executions
         #
         def durably_repeat(method, every:, till:, start_at: nil, max_attempts: 3, timeout: 1.hour, on_error: :continue, name: nil)
+          validate_step_name_segment!(name || method)
           step_name = "durably_repeat$#{name || method}"
 
           # Get or create the main coordination log for this periodic task
-          coordination_log = ExecutionLog.create_or_find_by!(
-            workflow: @workflow,
-            step_name: step_name
-          ) do |log|
+          coordination_log = find_or_create_execution_log!(step_name) do |log|
             log.started_at = Time.current
             log.metadata = {last_execution_at: nil}
           end
@@ -157,10 +155,7 @@ module ChronoForge
           step_name = "#{coordination_log.step_name}$#{next_execution_at.to_i}"
 
           # Create execution log for this specific repetition
-          repetition_log = ExecutionLog.create_or_find_by!(
-            workflow: @workflow,
-            step_name: step_name
-          ) do |log|
+          repetition_log = find_or_create_execution_log!(step_name) do |log|
             log.started_at = Time.current
             log.metadata = {
               scheduled_for: next_execution_at,
@@ -225,7 +220,7 @@ module ChronoForge
         rescue => e
           # Log the error
           Rails.logger.error { "Error in periodic task #{method}: #{e.message}" }
-          self.class::ExecutionTracker.track_error(@workflow, e)
+          self.class::ExecutionTracker.track_error(@workflow, e, execution_log: repetition_log)
 
           # Handle retry logic for this specific repetition
           if repetition_log.attempts < max_attempts

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

@@ -73,12 +73,10 @@ module ChronoForge
         # - Marks as completed when wait period has elapsed
         #
         def wait(duration, name)
+          validate_step_name_segment!(name)
           step_name = "wait$#{name}"
           # Find or create execution log
-          execution_log = ExecutionLog.create_or_find_by!(
-            workflow: @workflow,
-            step_name: step_name
-          ) do |log|
+          execution_log = find_or_create_execution_log!(step_name) do |log|
             log.started_at = Time.current
             log.metadata = {
               wait_until: duration.from_now

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

@@ -86,12 +86,10 @@ module ChronoForge
         # - Records final result (true for success, :timed_out for timeout)
         #
         def wait_until(condition, timeout: 1.hour, check_interval: 15.minutes, retry_on: [])
+          validate_step_name_segment!(condition)
           step_name = "wait_until$#{condition}"
           # Find or create execution log
-          execution_log = ExecutionLog.create_or_find_by!(
-            workflow: @workflow,
-            step_name: step_name
-          ) do |log|
+          execution_log = find_or_create_execution_log!(step_name) do |log|
             log.started_at = Time.current
             log.metadata = {
               timeout_at: timeout.from_now,
@@ -117,7 +115,7 @@ module ChronoForge
           rescue => e
             # Log the error
             Rails.logger.error { "Error evaluating condition #{condition}: #{e.message}" }
-            self.class::ExecutionTracker.track_error(workflow, e)
+            self.class::ExecutionTracker.track_error(workflow, e, execution_log: execution_log)
 
             # Optional retry logic
             if retry_on.include?(e.class)
@@ -162,7 +160,11 @@ module ChronoForge
               metadata: metadata.merge("result" => :timed_out)
             )
             Rails.logger.warn { "Timeout reached for condition '#{condition}'." }
-            raise WaitConditionNotMet, "Condition '#{condition}' not met within timeout period"
+            # Log here (with step context) rather than relying on the workflow-level
+            # rescue, which no longer logs ExecutionFailedError.
+            error = WaitConditionNotMet.new("Condition '#{condition}' not met within timeout period")
+            self.class::ExecutionTracker.track_error(workflow, error, execution_log: execution_log)
+            raise error
           end
 
           # Reschedule with delay

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

@@ -49,24 +49,20 @@ module ChronoForge
         #
         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|
+          execution_log = find_or_create_execution_log!("$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
+            # Mark execution log as completed. Attempt tracking and the terminal
+            # state are written together: completion is not retried on an
+            # attempt-count basis, so there is no need for a separate pre-write.
             execution_log.update!(
+              attempts: execution_log.attempts + 1,
+              last_executed_at: Time.current,
               state: :completed,
               completed_at: Time.current
             )
@@ -142,10 +138,7 @@ module ChronoForge
         #
         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|
+          execution_log = find_or_create_execution_log!("$workflow_failure$#{error_log.id}") do |log|
             log.started_at = Time.current
             log.metadata = {
               error_log_id: error_log.id
@@ -153,15 +146,14 @@ module ChronoForge
           end
 
           begin
-            execution_log.update!(
-              attempts: execution_log.attempts + 1,
-              last_executed_at: Time.current
-            )
-
             workflow.failed!
 
-            # Mark execution log as completed
+            # Mark execution log as completed. Attempt tracking and the terminal
+            # state are written together (failure handling is not retried on an
+            # attempt-count basis).
             execution_log.update!(
+              attempts: execution_log.attempts + 1,
+              last_executed_at: Time.current,
               state: :completed,
               completed_at: Time.current
             )
@@ -242,10 +234,9 @@ module ChronoForge
         # - Original exception is re-raised after logging
         #
         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
+          # Authoritative check at execution time (the record-level retry methods
+          # also check up front, but state may have changed since enqueue).
+          workflow.ensure_retryable!
 
           # Create an execution log for workflow retry
           execution_log = ExecutionLog.create!(

data/lib/chrono_forge/executor.rb

@@ -12,6 +12,12 @@ module ChronoForge
 
     class WorkflowNotRetryableError < NotExecutableError; end
 
+    class InvalidStepName < NotExecutableError; end
+
+    # "$" separates the segments of a step name (e.g. "durably_repeat$name$ts").
+    # User-supplied names/methods must not contain it.
+    STEP_NAME_DELIMITER = "$"
+
     include Methods
 
     # Add class methods
@@ -34,13 +40,13 @@ module ChronoForge
         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)
+        def retry_now(key, **)
+          perform_now(key, retry_workflow: true, **)
         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)
+        def retry_later(key, **)
+          perform_later(key, retry_workflow: true, **)
         end
       end
     end
@@ -74,9 +80,11 @@ module ChronoForge
 
         # Mark as complete
         complete_workflow!
-      rescue ExecutionFailedError => e
+      rescue ExecutionFailedError
+        # The step that raised this already logged the underlying cause (with its
+        # step/attempt context); ExecutionFailedError is control flow, not a new
+        # error, so re-logging it here would just duplicate the row.
         Rails.logger.error { "ChronoForge:#{self.class}(#{key}) step execution failed" }
-        self.class::ExecutionTracker.track_error(workflow, e)
         workflow.stalled!
         nil
       rescue HaltExecutionFlow
@@ -91,7 +99,7 @@ module ChronoForge
         raise
       rescue => e
         Rails.logger.error { "ChronoForge:#{self.class}(#{key}) workflow execution failed" }
-        error_log = self.class::ExecutionTracker.track_error(workflow, e)
+        error_log = self.class::ExecutionTracker.track_error(workflow, e, attempt: attempt)
 
         # Retry if applicable
         if should_retry?(e, attempt)
@@ -110,17 +118,52 @@ module ChronoForge
     private
 
     def setup_workflow!(key, options, kwargs)
-      @workflow = Workflow.create_or_find_by!(job_class: self.class.to_s, key: key) do |workflow|
-        workflow.options = options
-        workflow.kwargs = kwargs
-        workflow.started_at = Time.current
-      end
+      # SELECT-first: on every resume (the common case) the workflow already
+      # exists, so a plain lookup avoids an INSERT that would fail on the unique
+      # [job_class, key] index. create_or_find_by! is only reached on first-ever
+      # creation, where it also handles a concurrent insert race safely.
+      @workflow = Workflow.find_by(job_class: self.class.to_s, key: key) ||
+        Workflow.create_or_find_by!(job_class: self.class.to_s, key: key) do |workflow|
+          workflow.options = options
+          workflow.kwargs = kwargs
+          workflow.started_at = Time.current
+        end
     end
 
     def setup_context!
       @context = Context.new(workflow)
     end
 
+    # Idempotent, SELECT-first execution-log lookup.
+    #
+    # The engine replays the whole workflow body on every resume, so each durable
+    # step is looked up again every pass. A plain create_or_find_by! would INSERT
+    # first and fail on the unique index for the (overwhelmingly common) case
+    # where the step already exists — turning every replayed step into a wasted
+    # INSERT plus a burned sequence value. Looking up first means replays cost a
+    # single indexed SELECT.
+    #
+    # All lookups are by exact step_name (no method ever scans a workflow's logs),
+    # so a per-step lookup is also the right shape for durably_repeat workflows,
+    # which accumulate unbounded repetition logs: we touch only the rows we need,
+    # never the whole set. create_or_find_by! is used only on a miss, keeping
+    # creation safe if a lock takeover ever lets two executors race.
+    def find_or_create_execution_log!(step_name, &)
+      ExecutionLog.find_by(workflow: @workflow, step_name: step_name) ||
+        ExecutionLog.create_or_find_by!(workflow: @workflow, step_name: step_name, &)
+    end
+
+    # Guards the user-supplied portion of a step name (a custom name, method, or
+    # condition). The "$" separator is reserved for the framework's own segment
+    # structure, so a user value containing it would make step names ambiguous
+    # and corrupt the cleanup logic that parses them.
+    def validate_step_name_segment!(segment)
+      return unless segment.to_s.include?(STEP_NAME_DELIMITER)
+
+      raise InvalidStepName,
+        "ChronoForge step name may not contain '#{STEP_NAME_DELIMITER}' (reserved separator): #{segment.inspect}"
+    end
+
     def should_retry?(error, attempt_count)
       attempt_count < 3
     end

data/lib/chrono_forge/version.rb

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

data/lib/chrono_forge/workflow.rb

@@ -36,13 +36,36 @@ module ChronoForge
       stalled
     ]
 
-    # Serialization for metadata
-    serialize :metadata, coder: JSON
-
     def executable?
       idle? || running?
     end
 
+    # Only stalled or failed workflows can be re-executed.
+    def retryable?
+      stalled? || failed?
+    end
+
+    def ensure_retryable!
+      return if retryable?
+
+      raise Executor::WorkflowNotRetryableError,
+        "Cannot retry workflow(#{key}) in #{state} state. Only stalled or failed workflows can be retried."
+    end
+
+    # Re-execute this workflow from its record, without constantizing the job
+    # class or re-passing the key. Retryability is validated up front so a
+    # non-retryable workflow raises immediately rather than enqueuing a job that
+    # would fail in the worker.
+    def retry_now(**)
+      ensure_retryable!
+      job_klass.retry_now(key, **)
+    end
+
+    def retry_later(**)
+      ensure_retryable!
+      job_klass.retry_later(key, **)
+    end
+
     def job_klass
       job_class.constantize
     end

data/lib/generators/chrono_forge/install/USAGE

@@ -1,8 +1,10 @@
 Description:
-    Installs ChronoForge
+    Installs ChronoForge by copying all of its migrations into your app.
+    Idempotent: migrations that already exist are skipped.
 
 Example:
-    bin/rails g chrono_form:install
+    bin/rails g chrono_forge:install
 
-    This will create a new migration e.g:
+    This will create migrations e.g:
         20241221181505_install_chrono_forge.rb
+        20241221181506_add_chrono_forge_workflow_state_index.rb

data/lib/generators/chrono_forge/install/install_generator.rb

@@ -1,24 +1,22 @@
 # frozen_string_literal: true
 
 require "rails/generators/active_record/migration"
+require_relative "../migration_actions"
 
 module ChronoForge
+  # Installs all ChronoForge migrations into a new application. Idempotent:
+  # migrations that already exist are skipped, so re-running is safe.
   class InstallGenerator < Rails::Generators::Base
     include ::ActiveRecord::Generators::Migration
+    include ChronoForge::Generators::MigrationActions
 
-    source_root File.expand_path("templates", __dir__)
+    source_root File.expand_path("../templates", __dir__)
 
     def start
-      install_migrations
+      copy_chrono_forge_migrations
     rescue => err
       say "#{err.class}: #{err}\n#{err.backtrace.join("\n")}", :red
       exit 1
     end
-
-    private
-
-    def install_migrations
-      migration_template "install_chrono_forge.rb", "db/migrate/install_chrono_forge.rb"
-    end
   end
 end

data/lib/generators/chrono_forge/migration_actions.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ChronoForge
+  module Generators
+    # Shared migration-copy logic for the install and upgrade generators.
+    #
+    # Copying is idempotent: a migration whose name already exists in the host
+    # application's db/migrate is skipped, so it is safe to re-run either
+    # generator. `install` copies the full set (a fresh app has none yet);
+    # `upgrade` copies only the migrations a previously-installed app is missing.
+    # Both share this method — the difference is purely which migrations already
+    # exist in the target app.
+    #
+    # MIGRATIONS is listed in application order; copying preserves that order
+    # because each migration_template assigns the next sequential version number.
+    module MigrationActions
+      MIGRATIONS = %w[
+        install_chrono_forge
+        add_chrono_forge_workflow_state_index
+        add_chrono_forge_error_log_step_context
+      ].freeze
+
+      def copy_chrono_forge_migrations
+        MIGRATIONS.each do |name|
+          if chrono_forge_migration_exists?(name)
+            say_status :skip, "#{name} (migration already exists)", :yellow
+          else
+            migration_template "#{name}.rb", "db/migrate/#{name}.rb"
+          end
+        end
+      end
+
+      def chrono_forge_migration_exists?(name)
+        migrate_dir = File.join(destination_root, "db", "migrate")
+        Dir.glob(File.join(migrate_dir, "*_#{name}.rb")).any?
+      end
+    end
+  end
+end

data/lib/generators/chrono_forge/templates/add_chrono_forge_error_log_step_context.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Adds step context to error logs so each error can be attributed to the step
+# and attempt it came from — making error logs orderable and correlatable when
+# tailing a workflow, instead of an undifferentiated stream. Both columns are
+# nullable (a workflow-level error has no step), so this is a safe additive
+# change with no table rewrite.
+class AddChronoForgeErrorLogStepContext < ActiveRecord::Migration[7.1]
+  def change
+    add_column :chrono_forge_error_logs, :step_name, :string, if_not_exists: true
+    add_column :chrono_forge_error_logs, :attempt, :integer, if_not_exists: true
+  end
+end

data/lib/generators/chrono_forge/templates/add_chrono_forge_workflow_state_index.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Adds a composite [state, completed_at] index to chrono_forge_workflows. This
+# supports state-based monitoring (stalled/failed dashboards) and the retention
+# scan ChronoForge::Cleanup runs over completed workflows (the high-volume
+# terminal state), which filters by completed_at. The state prefix also serves
+# the smaller failed-workflow scan.
+#
+# Shipped as a standalone migration (rather than folded into the install
+# migration) so applications created with an earlier version of ChronoForge can
+# pick it up via `rails generate chrono_forge:upgrade`.
+class AddChronoForgeWorkflowStateIndex < ActiveRecord::Migration[7.1]
+  # On PostgreSQL the index is built CONCURRENTLY so it does not lock the table
+  # against writes, which also keeps strong_migrations satisfied. Concurrent
+  # index builds cannot run inside a transaction.
+  disable_ddl_transaction!
+
+  def change
+    add_index :chrono_forge_workflows, %i[state completed_at],
+      if_not_exists: true,
+      **chrono_forge_index_algorithm
+  end
+
+  private
+
+  def chrono_forge_index_algorithm
+    if connection.adapter_name.to_s.downcase.include?("postgresql")
+      {algorithm: :concurrently}
+    else
+      {}
+    end
+  end
+end

data/lib/generators/chrono_forge/upgrade/USAGE

@@ -0,0 +1,13 @@
+Description:
+    Upgrades an existing ChronoForge installation to the current schema.
+
+    New applications use `chrono_forge:install`. Applications that installed an
+    earlier version run this to add additive schema changes (currently the
+    chrono_forge_workflows [state, completed_at] index). The generated migration
+    is idempotent and safe to run even if the index already exists.
+
+Example:
+    bin/rails g chrono_forge:upgrade
+
+    This will create a new migration e.g:
+        20250603181505_add_chrono_forge_workflow_state_index.rb

data/lib/generators/chrono_forge/upgrade/upgrade_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators/active_record/migration"
+require_relative "../migration_actions"
+
+module ChronoForge
+  # Brings an existing ChronoForge installation up to the current schema by
+  # copying any migrations the application does not already have. Applications
+  # created with `chrono_forge:install` on the current version already have
+  # everything; older installs pick up the additive migrations (currently the
+  # chrono_forge_workflows [state, completed_at] index).
+  #
+  #   rails generate chrono_forge:upgrade
+  #   rails db:migrate
+  class UpgradeGenerator < Rails::Generators::Base
+    include ::ActiveRecord::Generators::Migration
+    include ChronoForge::Generators::MigrationActions
+
+    source_root File.expand_path("../templates", __dir__)
+
+    def start
+      copy_chrono_forge_migrations
+    rescue => err
+      say "#{err.class}: #{err}\n#{err.backtrace.join("\n")}", :red
+      exit 1
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chrono_forge
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-16 00:00:00.000000000 Z
+date: 2026-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -185,6 +185,8 @@ files:
 - gemfiles/rails_7.1.gemfile
 - gemfiles/rails_7.1.gemfile.lock
 - lib/chrono_forge.rb
+- lib/chrono_forge/cleanup.rb
+- lib/chrono_forge/cleanup_job.rb
 - lib/chrono_forge/error_log.rb
 - lib/chrono_forge/execution_log.rb
 - lib/chrono_forge/executor.rb
@@ -203,7 +205,12 @@ files:
 - lib/chrono_forge/workflow.rb
 - lib/generators/chrono_forge/install/USAGE
 - lib/generators/chrono_forge/install/install_generator.rb
-- lib/generators/chrono_forge/install/templates/install_chrono_forge.rb
+- lib/generators/chrono_forge/migration_actions.rb
+- lib/generators/chrono_forge/templates/add_chrono_forge_error_log_step_context.rb
+- lib/generators/chrono_forge/templates/add_chrono_forge_workflow_state_index.rb
+- lib/generators/chrono_forge/templates/install_chrono_forge.rb
+- lib/generators/chrono_forge/upgrade/USAGE
+- lib/generators/chrono_forge/upgrade/upgrade_generator.rb
 - sig/chrono_forge.rbs
 homepage: https://github.com/radioactive-labs/chrono_forge
 licenses: