# `PhoenixKit.Jobs.System`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v2.55.1/lib/phoenix_kit/jobs/system.ex#L1)

The trusted door into job runs, for callers that are **not a person**: the boot
sequence, a cron entry, a Mix task, a trigger such as a profile's revision
changing.

A separate module from `PhoenixKit.Jobs` on purpose. `Jobs.start/4` takes a
`Scope`, checks `jobs.manage` against the active role and attributes the run to
that person; here there is no one to check and no one to blame, and the mode is
stated by the caller — `:auto` (code reacting to something), `:cron` (a
schedule) or `:script` (a Mix task or console). A missing actor in the user door
can never be read as "the system", because the two are different functions.

Only call this from code that is itself trusted; never pass user input as the
kind or the mode. It is public API on purpose: code already running in the VM
can call anything, so hiding it would not make an authorization boundary — the
boundary is that user-facing paths pass a `Scope` to `PhoenixKit.Jobs`, which
checks it. The same holds for `PhoenixKit.Jobs.run_inline/3`.

# `start`

```elixir
@spec start(module(), PhoenixKit.Jobs.run_scope(), keyword()) ::
  {:ok, PhoenixKit.Jobs.Run.t(), :started | :existing} | {:error, term()}
```

Starts a run of `kind`, or returns the one already active. Options: `:args`,
`:mode` (`:auto` by default), `:source` (a short phrase for the history, kept
in the run's args as `"source"`).

`{:error, :raced}` means the trigger was not recorded (the active run finished
as this one arrived, three times over): try again. `{:error, :in_transaction}`
means it was called inside the caller's own transaction: call it after the commit.

---

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