# `Squidie.Runtime.Runner`
[🔗](https://github.com/dark-trench/squidie/blob/main/lib/squidie/runtime/runner.ex#L1)

Backend-neutral runtime entrypoints for host scheduler jobs.

Cron scheduler jobs should call this module when a serialized cron activation
is delivered. Step execution is claimed through `Squidie.execute_next/1`.

# `perform`

```elixir
@spec perform(
  map(),
  keyword()
) :: :ok | {:error, term()}
```

Executes one queued runtime payload.

Host job backends should store payloads produced by
`Squidie.Executor.Payload` and pass the payload back here when the job is
delivered. The runner accepts cron activation payloads only.

Cron payloads create a new run. Any scheduler metadata carried by
`Squidie.Executor.Payload.cron/3` is persisted into the run context before
the first workflow step is dispatched.

# `start_cron_trigger`

```elixir
@spec start_cron_trigger(String.t(), String.t(), keyword()) ::
  :ok
  | {:ok, {:duplicate_schedule_start, Ecto.UUID.t()}}
  | {:ok, {:skipped_schedule_start, Ecto.UUID.t()}}
  | {:error, term()}
```

Starts a workflow run from a serialized cron trigger.

This arity is useful for host schedulers that only know the workflow and
trigger names. It records schedule metadata, including the actual receive
timestamp. A signal id is recorded only when the scheduler supplies one or an
intended window is available for deterministic derivation.

# `start_cron_trigger`

```elixir
@spec start_cron_trigger(String.t(), String.t(), map(), keyword()) ::
  :ok
  | {:ok, {:duplicate_schedule_start, Ecto.UUID.t()}}
  | {:ok, {:skipped_schedule_start, Ecto.UUID.t()}}
  | {:error, term()}
```

Starts a workflow run from a serialized cron trigger and scheduler payload.

`signal_payload` is the scheduler metadata subset from a cron payload. When
it contains `"signal_id"` and `"intended_window"`, the runtime stores those
values under `run.context.schedule` before dispatching the first step,
making delayed delivery and restart recovery observable to workflow steps
and operators.

---

*Consult [api-reference.md](api-reference.md) for complete listing*