# wallet_compliance

OTP application for KYC/KYB compliance, AML screening, SAR workflows, and audit evidence export.

Phase 7 — Compliance, Risk Maturity, Audit Readiness.

## Responsibilities

- KYC/KYB case lifecycle and evidence tracking.
- AML suspicious activity alert creation and review workflow.
- SAR (Suspicious Activity Report) scaffolding with mandatory evidence fields.
- Compliance audit evidence export (JSON/CSV-ready).
- Control catalog and policy-to-technical-control mapping (ADR 0011).

## Public Interface

### Commands

| Module | Description |
|---|---|
| `WalletCompliance.Commands.SubmitKycCase` | Submit a new KYC/KYB case in :submitted state. |
| `WalletCompliance.Commands.ReviewKycCase` | Advance case: under_review -> approved | rejected. |
| `WalletCompliance.Commands.FileSuspiciousActivityReport` | File SAR with mandatory evidence fields. |

### Queries

| Module | Description |
|---|---|
| `WalletCompliance.Queries.GetKycStatus` | Get KYC case status by case_id or user_id. |
| `WalletCompliance.Queries.ListComplianceAlerts` | List AML alerts by status, user, or all. |

### Evidence Export

| Module | Description |
|---|---|
| `WalletCompliance.EvidenceExport` | `export_kyc/1`, `export_sar/1`, `export_aml/1`, `completeness_check/0`. |
| `WalletCompliance.ControlCatalog` | Policy-to-control mapping (CTRL-KYC-001, CTRL-AML-001, CTRL-AUD-001, etc.). |
| `WalletCompliance.EvidencePackage` | Evidence package format per ADR 0007/0011. |

## Domain Events

| Event | Trigger |
|---|---|
| `KycCaseSubmitted.v1` | KYC/KYB case submitted. |
| `KycCaseApproved.v1` | KYC/KYB case approved. |
| `KycCaseRejected.v1` | KYC/KYB case rejected. |
| `SarFiled.v1` | Suspicious Activity Report filed. |

## KYC/KYB State Machine

```
submitted -> under_review -> approved (terminal)
submitted -> under_review -> rejected (terminal)
submitted -> expired (terminal)
under_review -> expired (terminal)
```

## AML Alert Lifecycle

```
open -> under_review -> resolved (terminal)
open -> under_review -> escalated_to_sar (terminal)
open -> escalated_to_sar (terminal)
```

## Control Catalog (ADR 0011)

- `CTRL-KYC-001`: KYC decision event must include reviewer/system source and timestamp.
- `CTRL-KYC-002`: KYC case must reach terminal state to unblock onboarding.
- `CTRL-AML-001`: Active SAR requires at least one evidence reference.
- `CTRL-AML-002`: Suspicious transfer score above threshold must create review case.
- `CTRL-AUD-001`: Every compliance action emits an immutable AuditEvent.
- `CTRL-AUD-002`: Evidence export queryable by period, actor, action, outcome, control_id.

## Boundary Rules

- `wallet_compliance` may depend on: `wallet_shared_kernel`, `wallet_observability`, `wallet_events`.
- `wallet_compliance` must NOT depend on: `wallet_ledger`, `wallet_accounts`, `wallet_transfers` directly — consume events instead.
- `wallet_risk` is a peer domain sharing the compliance-risk event boundary.

## Tests

Run from umbrella root:
```
mix test apps/wallet_compliance
```