# wallet_events

**OTP app:** `:wallet_events`
**Module namespace:** `WalletEvents.*`
**Owner:** Platform Team

## Responsibilities
Event schema registry, outbox/inbox handling, and publish-subscribe reliability.

Per **ADR 0001**: this app owns the audit/event lineage system of record.
Per **ADR 0002**: all cross-app notifications use versioned domain events via outbox/inbox.

## Public API

### `WalletEvents.DomainEvent` (behaviour)
Behaviour contract for all versioned domain events.
Domain apps implement this behaviour to register their event types.
```elixir
defmodule MyApp.Events.TransferCompleted do
  @behaviour WalletEvents.DomainEvent
  def event_name, do: "TransferCompleted.v1"
  def event_version, do: 1
end
```

### `WalletEvents.OutboxEvent` (schema type)
Outbox event type definition for transactional outbox pattern.
Domain apps write events to the outbox within the same DB transaction as the command.

## Event Naming Convention (ADR 0001)
- Events are **past tense** with semantic version suffix: `NounVerbPastTense.v1`
- Breaking event changes require a version bump: `.v1` -> `.v2`

## Infrastructure vs Domain Events
This app provides **transport and reliability guarantees only**.
It does NOT own domain business events.
Domain apps define their own event structs implementing `DomainEvent` behaviour.

## Outbox/Inbox Pattern (ADR 0002)
1. Domain app writes command result + outbox event in same DB transaction.
2. Background relay job reads pending outbox events and dispatches them.
3. Consumers acknowledge events via inbox pattern.
4. Failed events are retried with backoff per ADR 0008 retry policy.

## Allowed Dependencies
- `wallet_shared_kernel` - Correlation ID and typed ID helpers