# `Jido.Messaging.DeadLetter`
[🔗](https://github.com/agentjido/jido_messaging/blob/v1.0.0/lib/jido_messaging/dead_letter.ex#L1)

Dead-letter storage and replay control plane for terminal outbound failures.

Dead-letter records are written when outbound gateway work reaches terminal
failure paths (including explicit load shedding). Replay execution is
partitioned by dead-letter id via `Jido.Messaging.DeadLetter.ReplayWorker`.

# `record`

```elixir
@type record() :: %{
  id: String.t(),
  instance_module: module(),
  status: record_status(),
  source: :outbound_gateway,
  inserted_at: DateTime.t(),
  updated_at: DateTime.t(),
  category: Jido.Messaging.OutboundGateway.error_category(),
  disposition: :retry | :terminal,
  reason: term(),
  retryable: boolean(),
  attempt: pos_integer() | nil,
  max_attempts: pos_integer() | nil,
  partition: non_neg_integer() | nil,
  routing_key: String.t() | nil,
  correlation_id: term(),
  idempotency_key: String.t() | nil,
  request: map(),
  diagnostics: map(),
  replay: replay_metadata()
}
```

# `record_status`

```elixir
@type record_status() :: :active | :archived
```

# `replay_metadata`

```elixir
@type replay_metadata() :: %{
  status: replay_status(),
  attempts: non_neg_integer(),
  last_attempt_at: DateTime.t() | nil,
  last_outcome: :ok | :error | nil,
  last_result: term() | nil
}
```

# `replay_response`

```elixir
@type replay_response() ::
  %{status: :already_replayed, record: record()}
  | %{
      status: :replayed,
      response: Jido.Messaging.OutboundGateway.success_response(),
      record: record()
    }
```

# `replay_status`

```elixir
@type replay_status() :: :never | :running | :succeeded | :failed
```

# `state`

```elixir
@type state() :: %{
  instance_module: module(),
  max_records: pos_integer(),
  records: %{optional(String.t()) => record()},
  order: [String.t()]
}
```

# `archive`

```elixir
@spec archive(module(), String.t()) :: :ok | {:error, :not_found | :unavailable}
```

Archive a dead-letter record.

# `capture_outbound_failure`

```elixir
@spec capture_outbound_failure(module(), map(), map(), map()) ::
  {:ok, record()} | {:error, :unavailable}
```

Capture a terminal outbound failure into dead-letter storage.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `config`

```elixir
@spec config(module()) :: keyword()
```

Returns dead-letter configuration for a messaging instance.

# `get`

```elixir
@spec get(module(), String.t()) ::
  {:ok, record()} | {:error, :not_found | :unavailable}
```

Get a dead-letter record by id.

# `list`

```elixir
@spec list(
  module(),
  keyword()
) :: {:ok, [record()]} | {:error, :unavailable}
```

List dead-letter records.

Options:
- `:status` - `:active`, `:archived`, or `:all` (default: `:all`)
- `:limit` - positive integer limit

# `purge`

```elixir
@spec purge(
  module(),
  keyword()
) :: {:ok, non_neg_integer()} | {:error, :unavailable}
```

Purge dead-letter records.

Options:
- `:status` - `:active`, `:archived`, or `:all` (default: `:archived`)
- `:older_than_ms` - only purge records older than this age

# `replay`

```elixir
@spec replay(module(), String.t(), keyword()) ::
  {:ok, replay_response()} | {:error, term()}
```

Replay a dead-letter record through partitioned replay workers.

# `replay_registry_name`

```elixir
@spec replay_registry_name(module()) :: atom()
```

Returns the registry used by replay workers for an instance module.

# `replay_supervisor_name`

```elixir
@spec replay_supervisor_name(module()) :: atom()
```

Returns the registered replay supervisor name for an instance module.

# `server_name`

```elixir
@spec server_name(module()) :: atom()
```

Returns the registered dead-letter server name for an instance module.

---

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