# `Squidie.Executor`
[🔗](https://github.com/dark-trench/squidie/blob/main/lib/squidie/executor.ex#L2)

Behaviour implemented by host applications to schedule Squidie cron work.

Jido-native execution is pulled through `Squidie.execute_next/1`. Host
applications that use external cron schedulers may still enqueue trigger
activations as plain `Squidie.Executor.Payload.cron/3` maps and deliver
them to `Squidie.Runtime.Runner.perform/2`.

# `cron_enqueue_opts`

```elixir
@type cron_enqueue_opts() :: [
  schedule_in: pos_integer(),
  signal_id: String.t(),
  intended_window: schedule_window()
]
```

# `enqueue_error`

```elixir
@type enqueue_error() :: term()
```

# `metadata`

```elixir
@type metadata() :: map()
```

# `schedule_window`

```elixir
@type schedule_window() :: %{
  optional(:start_at) => String.t(),
  optional(:end_at) => String.t(),
  optional(String.t()) => String.t()
}
```

# `enqueue_cron`

```elixir
@callback enqueue_cron(Squidie.Config.t(), module(), atom(), cron_enqueue_opts()) ::
  {:ok, metadata()} | {:error, enqueue_error()}
```

Enqueues or schedules a cron trigger activation.

Host schedulers can call this callback when a declared cron trigger fires, or
can enqueue `Squidie.Executor.Payload.cron/3` directly and deliver it to
`Squidie.Runtime.Runner.perform/2`.

When the scheduler knows the logical schedule window, pass `:signal_id` and
`:intended_window` through to `Squidie.Executor.Payload.cron/3`. Squidie
persists those values as run context before workflow processing starts, so
delayed workers do not need to infer the intended window from wall-clock time.

Cron triggers that opt into idempotency use the scheduler `:signal_id`, or a
deterministic id derived from a complete `:intended_window`, as the duplicate
start key. If the host omits both, the runtime rejects the start because it
cannot safely distinguish a new activation from a redelivery.

---

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