# Phase Handover — Loyalty 7.6 Wallet

## Metadata

| Field | Value |
| --- | --- |
| Phase ID | loyalty-7.6 |
| Title | Wallet |
| Status | Complete |
| Service(s) | loyalty (`loyalty-service`, port 8004) |
| Version | 0.7.6.0 |
| Date | 2026-07-26 |
| ADR(s) | ADR-001, ADR-003, ADR-006, ADR-011 |

## Reusable Components

| Component | Location | Reuse notes |
| --- | --- | --- |
| WalletAccount / WalletLedgerEntry | `app/models/wallet.py` | Immutable ledger pattern (gift cards 7.7) |
| WalletEngineService | `app/services/wallet_engine.py` | Credit/debit/adjust/transfer |
| Wallet validators | `app/validators/wallet.py` | Open-account + currency checks |

## Public APIs

| Method | Path | Auth / Permission | Notes |
| --- | --- | --- | --- |
| POST | `/api/v1/wallets` | `loyalty.wallets.create` | Open account |
| GET | `/api/v1/wallets/{id}/balance` | `loyalty.wallets.view` | Computed balance |
| GET | `/api/v1/wallets/{id}/ledger` | `loyalty.wallets.view` | Paginated entries |
| POST | `/api/v1/wallets/{id}/credit` | `loyalty.wallets.credit` | Idempotent optional |
| POST | `/api/v1/wallets/{id}/debit` | `loyalty.wallets.debit` | Rejects insufficient |
| POST | `/api/v1/wallets/{id}/adjust` | `loyalty.wallets.adjust` | Signed delta |
| POST | `/api/v1/wallets/{id}/transfer` | `loyalty.wallets.transfer` | Two-leg atomic |
| POST | `/api/v1/wallets/{id}/delete` | `loyalty.wallets.delete` | Soft close |

## Events

| Event type | Domain / Integration | Version |
| --- | --- | --- |
| `loyalty.wallet.opened` | Domain | 1 |
| `loyalty.wallet.credited` | Domain | 1 |
| `loyalty.wallet.debited` | Domain | 1 |
| `loyalty.wallet.adjusted` | Domain | 1 |
| `loyalty.wallet.transferred` | Domain | 1 |
| `loyalty.wallet.closed` | Domain | 1 |

## Extension Points

| Extension point | How to extend | Forbidden uses |
| --- | --- | --- |
| Ledger entry types | Add enum + validators + tests | Mutate existing rows |
| Balance source | Always SUM(ledger) | Add mutable balance column |
| Gift cards | Issue via 7.7 on top of wallet or separate ledger | Bypass wallet ledger for stored value without docs |

## Known Limitations

- No payment-provider settlement
- Gift cards deferred to 7.7
- No auto freeze/close scheduler

## Migration Notes

| Item | Detail |
| --- | --- |
| Alembic revision(s) | `0007_phase_76_wallet` |
| Upgrade steps | `alembic upgrade head` in loyalty service |
| Downgrade support | Yes |
| Breaking changes | None (additive) |

## Dependencies

| Dependency | Type | Required for |
| --- | --- | --- |
| loyalty-7.5 | Phase | Prior engines + programs/members |
| shared-lib | Library | Events, security, exceptions |

## Next Phase Entry

1. This handover + [loyalty-phase-7-6.md](../loyalty-phase-7-6.md)
2. Build Gift Card Platform; keep ledger immutability
3. Suggested next: `loyalty-7.7` Gift Card Platform

| Field | Value |
| --- | --- |
| Recommended next phase | loyalty-7.7 |
| Blockers for next phase | None |
| Entry checklist | Read 7.6 handover; never mutate wallet balances directly |

## Completion Sign-Off

- [x] Quality gates passed
- [x] Tests green (114)
- [x] Documentation updated
- [x] Progress / next-steps / registries updated
- [x] Service Snapshot regenerated

## Related Documents

- [loyalty-phase-7-6.md](../loyalty-phase-7-6.md)
- [loyalty-phase-7-5.md](../loyalty-phase-7-5.md)
- [ADR-011](../architecture/adr/ADR-011.md)