# `AshWorkflow.Entities.Every`
[🔗](https://github.com/team-alembic/ash_workflow/blob/v0.12.0/lib/ash_workflow/entities/every.ex#L1)

Defines a recurring action entity with its configuration schema.

`every` is not a timeout: nothing is timing out. It is a recurring action
that runs on an interval for as long as a record sits in its step. Firing
never leaves the step — there is no `transition_to` — so `every` always
requires an `action`.

## Storage

`AshWorkflow.Transformers.AddAttributes` adds one nilable
`:utc_datetime_usec` attribute per `every`, holding the instant it last
fired. Its `interval` is measured against that column, not against
`state_entered_at`, so two `every` entities on the same step — and any
`timeout` sharing the step — no longer share one anchor that one firing
resets out from under the others.

Named `<step>_<every>_last_fired_at` by default, or explicitly with
`last_fired_field`:

    every :reminder do
      interval {1, :hours}
      action :send_reminder
      last_fired_field :reminder_last_fired_at
    end

Not `field` — `AshWorkflow.Entities.Timeout`'s `field` names an anchor
AshWorkflow reads and never writes. `last_fired_field` names a column
AshWorkflow owns and writes on every fire. Reusing the name would give it
two opposite meanings.

A record whose column is still `nil` has never fired this `every`, and the
interval is then measured from `state_entered_at`, so the first firing lands
one whole interval after the record entered the step rather than on entry.
Both the generated Oban trigger and
`AshWorkflow.Scheduler.Precise.Timeline` apply that fallback.

## Bounding an `every` with `until`

`every` alone fires forever. `until` stops it after a fixed amount of
wall-clock time since the record entered the step:

    every :reminder do
      interval {2, :days}
      action :send_review_reminder
      until {8, :days}
    end

`until` is measured against `state_entered_at` directly. An `every`'s own
firing writes its `last_fired_field`, not `state_entered_at`, so
`state_entered_at` stays put for as long as the record occupies the step —
nothing moves the anchor `until` measures against. See
`AshWorkflow.Verifiers.ValidateEvery` for why `until` must be strictly
longer than `interval`.

Reaching the bound only stops the firing. It does not transition state —
compose a second, ordinary timeout with a `fire_after` equal to the bound
for "give up and move on".

## Bounding an `every` with `max_fires`

`max_fires` stops it after a number of fires in the current step visit:

    every :reminder do
      interval {2, :days}
      action :send_review_reminder
      max_fires 3
    end

## Spacing fires out with `backoff`

`backoff` grows the gap between fires. The first fire still lands one
`interval` after entry. After fire `n`, the next lands `interval` plus
`AshWorkflow.Entities.Retry.delay_ms/2` for attempt `n` later, so a fixed
duration adds the same delay to every later gap and `:exponential` adds
Oban's `n^4 + 15` seconds.

Both options add a `<step>_<every>_fires` integer column holding the fires
in the current step visit. A fire recorded before `state_entered_at` belongs
to an earlier visit, so the count restarts on re-entry.

# `duration_unit`

```elixir
@type duration_unit() :: AshWorkflow.Duration.unit()
```

# `t`

```elixir
@type t() :: %AshWorkflow.Entities.Every{
  __spark_metadata__: term(),
  action: atom(),
  backoff: AshWorkflow.Entities.Retry.backoff() | nil,
  check_interval: String.t() | nil,
  emits: [AshWorkflow.Entities.Emit.t()],
  interval: {pos_integer(), duration_unit()},
  last_fired_field: atom() | nil,
  max_fires: pos_integer() | nil,
  name: atom(),
  retry: AshWorkflow.Entities.Retry.t() | nil,
  self_scheduled?: boolean(),
  until: AshWorkflow.Duration.t() | nil
}
```

# `attribute_schema`

# `fires_field`

```elixir
@spec fires_field(atom(), t()) :: atom() | nil
```

The integer attribute counting this `every`'s fires in the current step
visit, `<step_name>_<every_name>_fires`, or `nil` when the `every` declares
neither `max_fires` nor `backoff` and so needs no count.

# `gap_ms`

```elixir
@spec gap_ms(
  AshWorkflow.Duration.t(),
  AshWorkflow.Entities.Retry.backoff() | nil,
  non_neg_integer()
) ::
  non_neg_integer()
```

The gap in milliseconds between fire number `fires` and the next one.

`fires` of 0 is the gap from step entry to the first fire, which is
`interval` whatever the `backoff`.

# `last_fired_field`

```elixir
@spec last_fired_field(atom(), t()) :: atom()
```

The attribute this `every` writes its last-fired instant to, and measures
`interval` against: `last_fired_field` if given, otherwise
`<step_name>_<every_name>_last_fired_at`.

# `next_due_at`

```elixir
@spec next_due_at(
  AshWorkflow.Duration.t(),
  AshWorkflow.Entities.Retry.backoff() | nil,
  DateTime.t() | nil,
  non_neg_integer() | nil,
  DateTime.t()
) :: DateTime.t()
```

The instant this `every` is next due, given the record's last-fired instant,
its fire count and its `state_entered_at`.

A `nil` last fire measures `interval` from `state_entered_at`. A last fire
from an earlier step visit counts as zero fires in this one.

# `validate_duration`

---

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