@spec count_crons(module()) :: {:ok, non_neg_integer()} | {:error, term()}

Counts scheduled PgFlow definitions.

@spec count_flows(module()) :: {:ok, non_neg_integer()}

Counts stored flow definitions.

@spec count_jobs(module()) :: {:ok, non_neg_integer()}

Counts stored job definitions.

@spec get_cron(module(), String.t()) ::
  {:ok, PgFlow.CronSummary.t()} | {:error, :not_found | term()}

Gets a scheduled definition with its stored schedule and operational data.

@spec get_flow(module(), String.t()) ::
  {:ok, PgFlow.DefinitionSummary.t()} | {:error, :not_found}

Gets a stored flow definition with its 24-hour operational statistics.

@spec get_job(module(), String.t()) ::
  {:ok, PgFlow.DefinitionSummary.t()} | {:error, :not_found}

Gets a stored job definition with its 24-hour operational statistics.

@spec get_step(module(), String.t(), String.t()) ::
  {:ok, PgFlow.Schema.Step.t()} | {:error, :not_found}

Gets a step using its complete composite key.

@spec list_crons(
  module(),
  keyword()
) :: {:ok, [PgFlow.CronSummary.t()]} | {:error, term()}

Lists scheduled definitions in deterministic slug order.

Supported options are :cursor and :limit.

@spec list_deps(module(), String.t()) :: {:ok, [PgFlow.Schema.Dep.t()]}

Lists dependency rows for a flow using the complete composite key.

@spec list_flows(
  module(),
  keyword()
) :: {:ok, [PgFlow.DefinitionSummary.t()]}

Lists stored flow definitions in deterministic slug order.

Supported options are :cursor and :limit.

@spec list_jobs(
  module(),
  keyword()
) :: {:ok, [PgFlow.DefinitionSummary.t()]}

Lists stored job definitions in deterministic slug order.

Supported options are :cursor and :limit.

@spec list_steps(module(), String.t()) :: {:ok, [PgFlow.Schema.Step.t()]}

Lists every stored step for a flow in execution order.

@spec unschedule(module(), String.t() | atom()) ::
  :ok | {:error, :invalid_flow_slug | :not_owned | term()}

Unschedules the pg_cron entry for a PgFlow definition.

An absent schedule is a successful no-op, and a dangling pgflow:<slug> schedule whose stored flow definition is missing is also removed.

Schedule ownership is preserved: only entries owned by the current database role are removed, including when the caller is a superuser. When a pgflow:<slug> schedule remains visible under another role afterwards, the schedule keeps firing and {:error, :not_owned} is returned. Row-level security on cron.job hides other roles' schedules from regular roles, so only callers that can see the surviving entry (such as superusers) receive the error.