# wallet_settlement

Async settlement batch processing, reconciliation pipeline, and exception management for the wallet platform.

## Responsibility
- Execute settlement batches across completed transfers.
- Run daily reconciliation passes comparing transfer records with internal references.
- Raise and manage exception records for detected mismatches.
- Provide operational visibility into batch progress and exception backlogs.

## Public Interface

### Commands
| Module | Action |
|---|---|
| `WalletSettlement.Commands.RunSettlementBatch` | Create + enqueue a settlement batch |
| `WalletSettlement.Commands.RunReconciliation` | Create + enqueue a reconciliation run |
| `WalletSettlement.Commands.ResolveSettlementException` | Resolve an open exception with audit note |

### Queries
| Module | Action |
|---|---|
| `WalletSettlement.Queries.GetSettlementBatch` | Get batch by ID |
| `WalletSettlement.Queries.ListSettlementBatches` | List batches (optionally by status) |
| `WalletSettlement.Queries.ListExceptions` | List exceptions (by batch, status, or all) |
| `WalletSettlement.Queries.GetReconciliationRun` | Get reconciliation run by ID |

### Events Emitted
| Event | Trigger |
|---|---|
| `SettlementBatchStarted.v1` | Batch transitions to :running |
| `SettlementBatchCompleted.v1` | Batch reaches :completed or :partial |
| `SettlementExceptionRaised.v1` | Mismatch detected during settlement/reconciliation |
| `ReconciliationCompleted.v1` | Reconciliation run completes |
| `ExceptionResolved.v1` | Exception marked as resolved |

## Queue Topology
See `WalletSettlement.QueueConfig` for full Oban queue configuration.

| Queue | Priority | Use |
|---|---|---|
| `:settlement_high` | 1 | Settlement batch execution |
| `:settlement_normal` | 2 | Reconciliation runs |
| `:settlement_low` | 3 | Exception status updates |

For CI (no Postgres), `WalletSettlement.JobQueue` provides an ETS-backed in-process
queue with equivalent retry/backoff and dead-letter semantics.

## Domain Rules
- Settlement batches are immutable once completed or failed.
- Exceptions require explicit resolution with an audit note.
- Reconciliation runs operate on a time window; Phase 5 uses in-memory transfer data.
  Phase 6 augments with external CBS ledger feed via `wallet_integrations`.

## Dependencies
- `wallet_shared_kernel`, `wallet_api_contracts`, `wallet_observability`, `wallet_events`
- `wallet_transfers` (read-only: query completed transfers for settlement)

## Allowed Callers
- `wallet_web` (admin settlement dashboard)
- `wallet_journey` (post-completion settlement trigger)
- Scheduled cron triggers via `JobQueue` or Oban scheduler

## Not Allowed
- Direct access to `wallet_ledger` tables.
- Initiating or completing transfers (owned by `wallet_transfers`).