@spec adjacent(module(), Ecto.UUID.t(), :next | :prev) ::
  {:ok, Ecto.UUID.t()} | {:error, :invalid_id | :invalid_direction | :not_found}

Gets the adjacent run UUID in newest-first navigation order.

:next selects the next older run and :prev selects the previous newer run. Timestamp ties are resolved by UUID.

@spec count(
  module(),
  keyword()
) :: {:ok, non_neg_integer()}

Counts runs matching the supplied filters.

Count ignores pagination options and accepts the same filter options as list/2.

@spec count_queue_messages(
  module(),
  String.t() | atom(),
  Ecto.UUID.t() | [Ecto.UUID.t()],
  keyword()
) ::
  {:ok, non_neg_integer()}
  | {:error, :invalid_id | :invalid_flow_slug | :invalid_location | term()}

Counts durable PGMQ messages belonging to one or more run UUIDs.

The count reads each message's embedded run_id, so it includes orphaned queue messages whose relational lifecycle rows no longer exist. The :location option accepts :all (the default), :live, or :archive. Missing queues and an empty run-ID list both return {:ok, 0}.

The JSON payload predicate is diagnostic-oriented and requires an O(queue size) scan unless the consumer adds matching expression indexes to its PGMQ queue tables.

@spec delete(module(), Ecto.UUID.t()) ::
  :ok | {:error, :invalid_id | :invalid_flow_slug | term()}

Deletes a run and all of its queued and persisted lifecycle data.

The operation locks an existing run and performs all cleanup in one transaction. Queue cleanup uses the exact run UUID embedded in each PGMQ payload, including orphaned messages without a task row. An absent run or queue is a successful no-op.

@spec get(module(), Ecto.UUID.t()) ::
  {:ok, PgFlow.Schema.Run.t()} | {:error, :invalid_id | :not_found}

Gets a persisted run by UUID.

@spec get_step_task(module(), Ecto.UUID.t(), String.t(), non_neg_integer()) ::
  {:ok, PgFlow.Schema.StepTask.t()} | {:error, :invalid_id | :not_found}

Gets one persisted task by run, step, and task index.

@spec get_with_states(module(), Ecto.UUID.t()) ::
  {:ok, PgFlow.Schema.Run.t()} | {:error, :invalid_id | :not_found}

Gets a persisted run with its step states preloaded in deterministic order.

@spec history(module(), String.t(), keyword()) :: {:ok, [PgFlow.RunHistoryCell.t()]}

Lists typed step-history cells for the most recent runs of a flow.

The :limit option controls how many runs are included, not the number of returned cells.

@spec list(
  module(),
  keyword()
) :: {:ok, [PgFlow.RunSummary.t()]} | {:error, :invalid_id}

Lists run summaries in newest-first order.

Supported options are :flow_slug, :status, :flow_type, :time_range, :started_after, :started_before, :input_contains, :cursor, and :limit. Explicit :started_after and :started_before bounds are inclusive. No time filter is applied unless a time option is supplied.

@spec list_run_tasks(module(), Ecto.UUID.t()) ::
  {:ok, [PgFlow.Schema.StepTask.t()]} | {:error, :invalid_id}

Lists every persisted task for a run in step and task-index order.

@spec list_step_states(module(), Ecto.UUID.t()) ::
  {:ok, [PgFlow.Schema.StepState.t()]} | {:error, :invalid_id}

Lists a run's persisted step states in execution order.

@spec list_step_tasks(module(), Ecto.UUID.t(), String.t()) ::
  {:ok, [PgFlow.Schema.StepTask.t()]} | {:error, :invalid_id}

Lists all persisted tasks for a run step in task-index order.

@spec make_available(module(), Ecto.UUID.t()) ::
  :ok | {:error, :invalid_id | :invalid_flow_slug | term()}

Makes every queued task for a run immediately visible to workers.

Visibility is scoped by the exact run UUID embedded in the PGMQ payload so it also covers an orphaned queue message whose task row is missing.

An absent run or queue is a successful no-op.