# `Accrue.Actor`
[🔗](https://github.com/szTheory/accrue/blob/accrue-v0.3.0/lib/accrue/actor.ex#L1)

Process-dictionary-backed actor context for the Events ledger (D-15).

Callers upstream of `Accrue.Events.record/1` set the current actor via
`put_current/1` or scope a block with `with_actor/2`. `Events.record/1`
reads `current/0` and stamps each event with the actor metadata.

The actor type is a fixed enum: `:user | :system | :webhook | :oban | :admin`.
Unknown atoms raise `ArgumentError` at put time so typos fail loud.

`Accrue.Plug.PutActor` (Phase 2) and the Oban worker middleware wire this
automatically; library callers can also manage it themselves with
`with_actor/2`.

# `actor_type`

```elixir
@type actor_type() :: :user | :system | :webhook | :oban | :admin
```

# `t`

```elixir
@type t() :: %{type: actor_type(), id: String.t() | nil}
```

# `current`

```elixir
@spec current() :: t() | nil
```

Reads the current actor from the process dictionary. Returns `nil` when
unset.

# `current_operation_id`

```elixir
@spec current_operation_id() :: String.t() | nil
```

Returns the current operation ID from the process dictionary, or `nil`
if unset. Used by `Accrue.Processor.Stripe` as the seed for
deterministic idempotency keys (D2-12).

# `current_operation_id!`

```elixir
@spec current_operation_id!() :: String.t()
```

Raising variant of `current_operation_id/0`.

Behaviour depends on `:idempotency_mode` (D3-63):

  * `:strict` — raises `Accrue.ConfigError` with a message pointing at
    `Accrue.Plug.PutOperationId` or the `:operation_id` call option.
  * Any other value (default `:warn`) — generates a random UUID via
    `Ecto.UUID.generate/0`, logs a `Logger.warning/1`, and returns it.
    The generated value is NOT written back to the process dict so
    the warning fires on every call until the caller wires a real ID.

# `put_current`

```elixir
@spec put_current(t() | nil) :: :ok
```

Stores an actor in the process dictionary. Raises `ArgumentError` on
unknown actor type.

# `put_operation_id`

```elixir
@spec put_operation_id(String.t() | nil) :: :ok
```

Stores an operation ID in the process dictionary. Oban middleware and
webhook plug set this automatically so downstream processor calls
produce deterministic idempotency keys.

# `types`

```elixir
@spec types() :: [actor_type()]
```

Returns the fixed actor-type enum. Useful for downstream validation.

# `with_actor`

```elixir
@spec with_actor(t(), (-> any())) :: any()
```

Runs `fun` with `actor` as the current actor, restoring the prior
value (or clearing it) in an `after` block.

---

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