TorbatYar/docs/phase-handover/phase-7-6.md

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
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

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

Related Documents

• loyalty-phase-7-6.md
• loyalty-phase-7-5.md
• ADR-011