# `AshWorkflow.Transformers.AddAttributes`
[🔗](https://github.com/team-alembic/ash_workflow/blob/v0.12.0/lib/ash_workflow/transformers/add_attributes.ex#L1)

Adds the `state_entered_at` attribute if not already defined on the resource.

This attribute tracks when the workflow entered its current state. It is used by
timeout triggers to calculate whether a deadline has passed. The attribute is:

- Type: `:utc_datetime_usec`
- `allow_nil?: false` with a default of `DateTime.utc_now/0`
- `public?: true` and `writable?: false`

`writable?: false` keeps the attribute out of every action's `accept` list and
rejects it as an argument, so nothing outside AshWorkflow can move a record's
anchor. `AshWorkflow.Changes.RecordEvent` writes it with
`Ash.Changeset.force_change_attribute/3`, which bypasses `writable?`, and the
atomic path writes it through the `%{state_entered_at: expr(now())}` map
`atomic/3` returns. Both are unaffected.

Every deadline on a step measures from this attribute, so a write from
outside moves every one of them at once. A caller that genuinely needs to set
it (backfilling imported records, say) can still reach it with
`force_change_attribute/3` or the data layer directly.

Does NOT add the `:state` attribute — that is handled by
AshStateMachine's `AddState` transformer.

If the user has already defined a `state_entered_at` attribute, this transformer
is a no-op.

## `every` last-fired columns

Also adds one nilable `:utc_datetime_usec` attribute per `every`, named by
`AshWorkflow.Entities.Every.last_fired_field/2`. `AshWorkflow.Changes.RecordEvent`
writes it on that `every`'s firing, and `AshWorkflow.Transformers.AddScheduler`
measures the `every`'s `interval` against it instead of `state_entered_at`. See
`AshWorkflow.Entities.Every` for why firing no longer touches
`state_entered_at`.

Nilable because an `every` that has not fired yet has no last-fired instant,
which is also the case for an in-flight record written before the column
existed. A `nil` column means the interval is measured from
`state_entered_at` instead, so a record entering the step fires one whole
interval later and needs no backfill.

An `every` declaring `max_fires` or `backoff` also gets an integer column
named by `AshWorkflow.Entities.Every.fires_field/2`, defaulting to 0, which
`AshWorkflow.Changes.RecordEvent` increments on each fire.

## Action timeout fired columns

Also adds one nilable `:utc_datetime_usec` attribute per action timeout,
named by `AshWorkflow.Entities.Timeout.fired_field/2`. An action timeout does
not change state, so `AshWorkflow.Changes.RecordEvent` writes this column
when it fires, and `AshWorkflow.Scheduler.Work.not_fired/1` stops the
timeout matching again until its deadline moves past it. A transition
timeout gets no column, since leaving the step records that it fired.

Nilable because a timeout that has not fired yet has no fired instant. A
record written before the column existed reads `nil` too, so a timeout that
already fired for it fires once more after the upgrade.

# `after?`

# `after_compile?`

# `before?`

# `transform`

---

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