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

Squidie-native runtime command signal envelope.

These signals describe product-level runtime commands before any adapter turns
them into a backend primitive such as `Jido.Signal`. Workflow authors and host
apps should not need to construct raw backend signals.

| type | payload |
| --- | --- |
| `:start_run` | `%{workflow: String.t(), trigger: String.t() | nil, input: map()}` |
| `:start_cron` | `%{workflow: String.t(), trigger: String.t(), input: map()}` |
| `:approve_run` | `%{run_id: Ecto.UUID.t(), attributes: map()}` |
| `:reject_run` | `%{run_id: Ecto.UUID.t(), attributes: map()}` |
| `:resume_run` | `%{run_id: Ecto.UUID.t(), attributes: map()}` |
| `:cancel_run` | `%{run_id: Ecto.UUID.t()}` |
| `:replay_run` | `%{run_id: Ecto.UUID.t(), allow_irreversible: boolean()}` |

Every signal carries caller metadata, an occurrence timestamp, and an optional
idempotency key. Cron signals derive the key from scheduler identity when the
caller does not provide one.

# `command_type`

```elixir
@type command_type() ::
  :start_run
  | :start_cron
  | :approve_run
  | :reject_run
  | :resume_run
  | :cancel_run
  | :replay_run
```

# `error`

```elixir
@type error() :: {:invalid_signal, term()}
```

# `payload`

```elixir
@type payload() :: %{
  optional(:workflow) => String.t(),
  optional(:trigger) => String.t() | nil,
  optional(:input) => map(),
  optional(:run_id) => Ecto.UUID.t(),
  optional(:attributes) => map(),
  optional(:allow_irreversible) => boolean()
}
```

# `t`

```elixir
@type t() :: %Squidie.Runtime.Signal{
  idempotency_key: String.t() | nil,
  metadata: map(),
  occurred_at: DateTime.t(),
  payload: payload(),
  type: command_type()
}
```

# `approve_run`

```elixir
@spec approve_run(Ecto.UUID.t(), map(), keyword()) :: {:ok, t()} | {:error, error()}
```

Builds a command signal for approving a blocked run.

# `cancel_run`

```elixir
@spec cancel_run(
  Ecto.UUID.t(),
  keyword()
) :: {:ok, t()} | {:error, error()}
```

Builds a command signal for canceling a run.

# `reject_run`

```elixir
@spec reject_run(Ecto.UUID.t(), map(), keyword()) :: {:ok, t()} | {:error, error()}
```

Builds a command signal for rejecting a blocked run.

# `replay_run`

```elixir
@spec replay_run(
  Ecto.UUID.t(),
  keyword()
) :: {:ok, t()} | {:error, error()}
```

Builds a command signal for replaying a run.

# `resume_run`

```elixir
@spec resume_run(Ecto.UUID.t(), map(), keyword()) :: {:ok, t()} | {:error, error()}
```

Builds a command signal for resuming a blocked run.

# `start_cron`

```elixir
@spec start_cron(module() | String.t(), atom() | String.t(), map(), keyword()) ::
  {:ok, t()} | {:error, error()}
```

Builds a command signal for starting a workflow run from a cron activation.

# `start_run`

```elixir
@spec start_run(module() | String.t(), atom() | String.t() | nil, map(), keyword()) ::
  {:ok, t()} | {:error, error()}
```

Builds a command signal for starting a workflow run.

---

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