refactor: consolidate run and work order state definitions (#4600)

* refactor: consolidate run and work order state definitions

Hardcoded run and work order state lists were scattered across multiple
files (dashboard_stats.ex, query.ex, impeded_project_helper.ex,
dashboard_components.ex, search_params.ex, and tests), creating a
maintenance burden where any state change required manual updates in
multiple locations that the compiler cannot catch.

Add Run.active_states/0 for [:available, :claimed, :started],
WorkOrder.states/0 for all valid states, and WorkOrder.active_states/0
for [:pending, :running]. Replace all hardcoded state lists across the
codebase with references to these canonical functions.

Derive SearchParams.@statuses from WorkOrder.states/0 to keep the
filter UI in sync automatically.

Closes #4589

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>

* style: fix formatting in search_params.ex

Align pipe operator to satisfy mix format --check-formatted.

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>

* refactor: use single source of truth for state definitions

Derived excluded_states in dashboard_stats from WorkOrder.active_states
instead of hardcoding. Introduced @active_states module attribute in
Run to share between the function and Ecto.Enum definition.

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>

* refactor: use WorkOrder.active_states in workorder_component

The retry-button visibility check used a hardcoded [:pending, :running]
list introduced after this branch was opened (#4578). Route it through
WorkOrder.active_states/0 to keep the single-source-of-truth invariant
from #4589 intact.

* refactor: tighten state-list reuse after code review

- Run.@States now reuses @active_states instead of re-listing the active
  states inline (single source of truth within the schema module).
- dashboard_stats batch helper uses the @wo_active module attribute,
  matching its sibling helper instead of calling WorkOrder.active_states/0
  inline.

---------

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Co-authored-by: Stuart Corbishley <corbish@gmail.com>

Author: officialasishkumar

CHANGELOG.md

@@ -19,6 +19,12 @@ and this project adheres to
 
 ### Changed
 
+- Consolidated run and work order state definitions into single source of truth
+  by adding `Run.active_states/0`, `WorkOrder.states/0`, and
+  `WorkOrder.active_states/0` and replacing all hardcoded state lists across the
+  codebase
+  [#4589](https://github.com/OpenFn/lightning/issues/4589)
+
 ### Fixed
 
 ## [2.16.7] - 2026-06-04

lib/lightning/dashboard_stats.ex

@@ -11,6 +11,8 @@ defmodule Lightning.DashboardStats do
   alias Lightning.Workflows.Workflow
   alias Lightning.WorkOrder
 
+  @wo_active WorkOrder.active_states()
+  @run_active Run.active_states()
   @days_back 30
 
   defmodule WorkflowStats do
@@ -58,7 +60,7 @@ defmodule Lightning.DashboardStats do
     last_workorders = batch_get_last_workorders(workflow_ids)
 
     last_failed_workorders =
-      batch_get_last_workorders(workflow_ids, [:pending, :running, :success])
+      batch_get_last_workorders(workflow_ids, @wo_active ++ [:success])
 
     Enum.map(workflows, fn workflow ->
       wf_id = workflow.id
@@ -201,7 +203,7 @@ defmodule Lightning.DashboardStats do
   end
 
   defp get_last_failed_workorder(workflow, %{state: :success}) do
-    excluded_states = [:pending, :running, :success]
+    excluded_states = @wo_active ++ [:success]
     get_last_workorder(workflow, excluded_states)
   end
 
@@ -238,7 +240,7 @@ defmodule Lightning.DashboardStats do
       {:success, cnt}, acc ->
         %{acc | success: cnt}
 
-      {state, cnt}, acc when state in [:pending, :running] ->
+      {state, cnt}, acc when state in @wo_active ->
         Map.update!(acc, :pending, &(&1 + cnt))
 
       {_other, cnt}, acc ->
@@ -260,7 +262,7 @@ defmodule Lightning.DashboardStats do
       {:success, cnt}, acc ->
         %{acc | success: cnt}
 
-      {state, cnt}, acc when state in [:available, :claimed, :started] ->
+      {state, cnt}, acc when state in @run_active ->
         Map.update!(acc, :pending, &(&1 + cnt))
 
       {_other, cnt}, acc ->
@@ -342,7 +344,7 @@ defmodule Lightning.DashboardStats do
           :success ->
             %{current | success: cnt}
 
-          s when s in [:pending, :running] ->
+          s when s in @wo_active ->
             Map.update!(current, :pending, &(&1 + cnt))
 
           _ ->
@@ -370,7 +372,7 @@ defmodule Lightning.DashboardStats do
           :success ->
             %{current | success: cnt}
 
-          s when s in [:available, :claimed, :started] ->
+          s when s in @run_active ->
             Map.update!(current, :pending, &(&1 + cnt))
 
           _ ->

lib/lightning/runs/prom_ex_plugin/impeded_project_helper.ex

@@ -25,9 +25,11 @@ defmodule Lightning.Runs.PromExPlugin.ImpededProjectHelper do
         select: w.workflow_id,
         distinct: true
 
+    in_progress = Lightning.Run.active_states() -- [:available]
+
     in_progress_runs_query =
       from r in Lightning.Run,
-        where: r.state in [:claimed, :started],
+        where: r.state in ^in_progress,
         join: w in assoc(r, :work_order),
         group_by: w.workflow_id,
         select: %{workflow_id: w.workflow_id, count: count(r.id)}

lib/lightning/runs/query.ex

@@ -231,7 +231,7 @@ defmodule Lightning.Runs.Query do
     # Step 1: Rank runs within each workflow by priority and insertion time
     ranked_runs_query =
       from(r in Run,
-        where: r.state in [:available, :claimed, :started],
+        where: r.state in ^Run.active_states(),
         join: wo in assoc(r, :work_order),
         join: w in assoc(wo, :workflow),
         join: p in assoc(w, :project)

lib/lightning/runs/run.ex

@@ -41,6 +41,8 @@ defmodule Lightning.Run do
              :final_dataclip_id
            ]}
 
+  @active_states [:available, :claimed, :started]
+
   @final_states [
     :success,
     :failed,
@@ -51,7 +53,7 @@ defmodule Lightning.Run do
     :lost
   ]
 
-  @states [:available, :claimed, :started] ++ @final_states
+  @states @active_states ++ @final_states
 
   @doc """
   Returns all possible states for a run.
@@ -63,6 +65,13 @@ defmodule Lightning.Run do
   """
   def final_states, do: @final_states
 
+  @doc """
+  Returns the list of active (in-progress) states for a run.
+
+  These are all non-final states: available, claimed, and started.
+  """
+  def active_states, do: @active_states
+
   @doc """
   Returns the list of failure states for a run.
 

lib/lightning/workorders/search_params.ex

@@ -21,7 +21,8 @@ defmodule Lightning.WorkOrders.SearchParams do
              :sort_direction
            ]}
 
-  @statuses ~w(pending running success failed crashed killed cancelled lost exception rejected)
+  @statuses Lightning.WorkOrder.states()
+            |> Enum.map(&Atom.to_string/1)
   @statuses_set MapSet.new(@statuses)
   @search_fields ~w(id body log dataclip_name)
 

lib/lightning/workorders/workorder.ex

@@ -21,8 +21,10 @@ defmodule Lightning.WorkOrder do
           workflow: Workflow.t() | Ecto.Association.NotLoaded.t()
         }
 
+  @active_states [:pending, :running]
+
   @state_values Enum.concat(
-                  [:rejected, :pending, :running],
+                  [:rejected | @active_states],
                   Run.final_states()
                 )
 
@@ -31,6 +33,11 @@ defmodule Lightning.WorkOrder do
   """
   def states, do: @state_values
 
+  @doc """
+  Returns the list of active (in-progress) work order states.
+  """
+  def active_states, do: @active_states
+
   @derive {Jason.Encoder,
            only: [
              :id,

lib/lightning_web/live/run_live/workorder_component.ex

@@ -5,6 +5,7 @@ defmodule LightningWeb.RunLive.WorkOrderComponent do
   use LightningWeb, :live_component
 
   import LightningWeb.RunLive.Components
+  alias Lightning.WorkOrder
   alias Phoenix.LiveView.JS
 
   @impl true
@@ -261,7 +262,7 @@ defmodule LightningWeb.RunLive.WorkOrderComponent do
                   <.icon name="hero-x-mark-mini" class="h-4 w-4" />
                 </button>
               <% end %>
-              <%= if @work_order.state not in [:pending, :running] do %>
+              <%= if @work_order.state not in WorkOrder.active_states() do %>
                 <%= if wo_dataclip_available?(@work_order) and @can_run_workflow do %>
                   <button
                     type="button"

lib/lightning_web/live/workflow_live/dashboard_components.ex

@@ -4,6 +4,7 @@ defmodule LightningWeb.WorkflowLive.DashboardComponents do
 
   alias Lightning.DashboardStats.ProjectMetrics
   alias Lightning.Projects.Project
+  alias Lightning.WorkOrder
   alias Lightning.WorkOrders.SearchParams
   alias LightningWeb.Components.Common
   alias LightningWeb.WorkflowLive.Helpers
@@ -455,7 +456,7 @@ defmodule LightningWeb.WorkflowLive.DashboardComponents do
     <div>
       <div class="flex items-center gap-x-2">
         <span class="relative inline-flex h-2 w-2">
-          <%= if @state in [:pending, :running] do %>
+          <%= if @state in WorkOrder.active_states() do %>
             <span class={[
               "animate-ping absolute inline-flex h-full w-full rounded-full opacity-75",
               @dot_color

test/lightning/digest_email_worker_test.exs

@@ -153,7 +153,7 @@ defmodule Lightning.DigestEmailWorkerTest do
       workflow = insert(:simple_workflow, project: project)
 
       # Create workorders in non-final states (these should not be counted as failed)
-      create_runs(workflow, [:pending, :running])
+      create_runs(workflow, Lightning.WorkOrder.active_states())
 
       # Create one actual failed run for comparison
       create_runs(workflow, [:failed])