Defines a workflow timeout entity with its configuration schema.

The field option

By default, timeouts measure duration against state_entered_at — the timestamp of when the workflow entered its current state. The field option overrides this to measure against any datetime attribute or calculation on the resource.

This enables data-driven deadlines: "3 months since their last session" rather than "3 months since they entered the active state."

The fire_at option

fire_at names a datetime attribute or expression calculation that already holds the deadline instant, rather than an anchor to measure an offset from:

timeout :dormant do
  fire_at :next_check_at
  transition_to :dormant_review
end

The timeout fires once next_check_at has passed, at whatever resolution the selected scheduler polls or arms timers with.

fire_at and fire_after are mutually exclusive, and exactly one of them is required. field is the anchor fire_after measures from, so it has no meaning alongside fire_at and is rejected in combination with it.

AshWorkflow.Scheduler.due_at/2 reads the deadline field with Map.get/2, so a fire_at pointing at an expression calculation only holds a value once that calculation has been loaded. AshWorkflow.Scheduler.Precise.Timeline loads it with the records it arms timers from.

For a recurring action that fires on an interval for as long as a record sits in its step, use AshWorkflow.Entities.Every instead — see its moduledoc for why that is a separate entity rather than a repeat option here.