# First-Wave Scope and Non-Goals

Date: 2026-03-30
Status: approved
Reference: docs/multi-wallet/deliverables/capability-matrix.md

## 1. First-Wave (P0) Scope

The first wave delivers the minimum viable multi-wallet capability. All 30 P0 items from the capability matrix are in scope.

### 1.1 Scope Summary

**Wallet Product Lifecycle (7 P0 capabilities):**
- Create, list, get, update, freeze, unfreeze, close wallet products
- Multiple same-type per user support

**Sub-wallet Lifecycle (7 P0 capabilities):**
- Create (with auto-default), list, get, freeze, unfreeze, close sub-wallets
- Transfer between sub-wallets within same wallet product

**Multi-Currency (2 P0 capabilities):**
- Primary currency set at creation (immutable)
- One-primary invariant enforcement

**Ledger Integration (6 P0 capabilities):**
- Credit/debit to sub-wallets with per-sub-wallet balance tracking
- Sub-wallet transfer posting (linked entries)
- Freeze-state posting guard
- Balance queries (sub-wallet and aggregate)
- Idempotency enforcement

**API (4 P0 capabilities):**
- Wallet product REST endpoints
- Sub-wallet REST endpoints
- Sub-wallet transfer endpoint
- Backward compatibility for existing account endpoints

**Eventing (4 P0 capabilities):**
- Lifecycle events for wallet products and sub-wallets
- Transfer events
- Audit events for sensitive actions

### 1.2 Delivery Phases (P0 items by program phase)

| Program Phase | P0 Capabilities | Topics |
|---|---|---|
| Phase 2 | 0 (contracts only) | Domain state machines, event contracts, ADR conformance |
| Phase 3 | 0 (schema only) | 3 new tables, 4 table modifications, indexes, backfill plan |
| Phase 4 | 14 | WP-01..06,09,10 + SW-01..03,05..07 + MC-01,05 |
| Phase 5 | 7 | LT-01..06,08 + SW-08 |
| Phase 6 | 4 | API-01..03,07 |
| Phase 7 | 4 | EC-01..04 |
| Phase 8 | 0 | E2E validation and sign-off |
| Phase 9 | 0 | Rollout and hypercare |

### 1.3 Success Criteria for First Wave

1. A user can create multiple wallet products of any type.
2. Each wallet product has a default sub-wallet created automatically.
3. Users can create additional sub-wallets within a wallet product.
4. Funds can be transferred between sub-wallets within the same wallet product.
5. Freezing a wallet product cascades to all sub-wallets.
6. Closing a wallet product requires all sub-wallets closed with zero balance.
7. Existing API clients continue to work without changes via backward compatibility resolver.
8. All mutations are idempotent and emit domain + audit events.
9. All P0 tests pass with 0 failures.
10. Data backfill for existing accounts is verified.

## 2. Explicit Non-Goals (Deferred)

The following are explicitly NOT in the first wave:

| Item | Reason | Deferred To |
|---|---|---|
| WP-07/WP-08: Suspend/resume wallet product | P1 — suspend/resume is operational; freeze/unfreeze covers safety | Wave 2 |
| SW-04: Update sub-wallet metadata | P1 — metadata update is non-critical | Wave 2 |
| SW-09: Transfer across wallet products (same user) | P1 — requires currency compatibility; within-product covers core use case | Wave 2 |
| SW-10: Transfer cross-user via sub-wallets | P2 — existing P2P transfer covers cross-user; sub-wallet granularity is premium | Wave 3 |
| MC-02/MC-03: Display-only currencies | P1 — display is additive; primary currency is sufficient for launch | Wave 2 |
| MC-04: Disable/enable display currency | P2 — depends on MC-02 | Wave 3 |
| LT-07: FX conversion records | P2 — no cross-currency in wave 1 | Wave 3 |
| API-04: Currency config endpoints | P1 — depends on MC-02 | Wave 2 |
| API-05: Customer LiveView for multi-wallet | P1 — REST API is sufficient for launch; LiveView is UX enhancement | Wave 2 |
| API-06: Admin LiveView for multi-wallet | P1 — admin can use API; LiveView is convenience | Wave 2 |
| EC-05: Telemetry spans | P1 — events and audit cover observability; spans are optimization | Wave 2 |
| EC-06: Compliance control checks | P1 — existing compliance controls apply; multi-wallet specific controls are additive | Wave 2 |

## 3. Dependency Register

### 3.1 Internal Dependencies

| Dependency | Type | Owner | Status | Impact if Blocked |
|---|---|---|---|---|
| wallet_accounts: Account struct and store | Extend | Accounts team | Ready | Blocks all WP/SW capabilities |
| wallet_database: Ecto Repo and migrations | Extend | Database team | Ready | Blocks Phase 3 persistence |
| wallet_ledger: LedgerStore and Entry | Extend | Ledger team | Ready | Blocks Phase 5 posting |
| wallet_transfers: Transfer state machine | Extend | Transfers team | Ready | Blocks SW-08 transfer |
| wallet_events: DomainEvent behaviour | Reuse | Events team | Ready | Blocks event definitions |
| wallet_state: Idempotency contract | Reuse | Platform team | Ready | Blocks LT-08 idempotency |
| wallet_web: Router and API controllers | Extend | Web team | Ready | Blocks Phase 6 API |
| wallet_shared_kernel: TypedId | Reuse | Kernel team | Ready | Used for new ID generation |

### 3.2 External Dependencies

| Dependency | Type | Owner | Status | Impact if Blocked |
|---|---|---|---|---|
| MySQL database availability | Infra | Platform | Available | Blocks migration testing |
| FX rate provider (AFEX) | Integration | Integrations team | Existing | Only needed for Wave 2 (MC-02) |

### 3.3 Pre-existing Bugs to Fix (Pre-Phase 3)

| Bug | Impact | Fix In |
|---|---|---|
| Account struct has `close_reason`/`closed_by` but DB migration lacks these columns | Close reason data lost | Phase 3 migration |
| AccountStore lacks user_id secondary index | Slow list_by_user queries | Phase 3 (when adding WalletProductStore with proper indexes) |
| Event payload key inconsistency (payload vs data) | Minor; no data loss | Phase 7 standardization |

## 4. Risk Mitigations

| Risk | Mitigation |
|---|---|
| R1: Existing table model diverges | Gap analysis complete (Section 2.3 of ownership map). All gaps have resolution paths. No incompatible blockers found. |
| R2: Migration downtime | All schema changes are nullable column additions or new tables. No table locks expected. Backfill runs asynchronously. |
| R3: Cross-currency regression | Wave 1 is single-currency only. Cross-currency deferred to Wave 2 with explicit FX testing. |
| R4: Idempotency gaps | Existing idempotency contract (wallet_state) is reused. All new commands require idempotency key. |
| R5: Incomplete audit trail | All P0 commands emit both domain events and audit events. Event matrix validated in Phase 7. |

## 5. Wave Timeline Estimate

| Phase | Duration | Dependencies |
|---|---|---|
| Phase 2: Domain contracts | 1 sprint | Phase 1 complete (this document) |
| Phase 3: Persistence | 1 sprint | Phase 2 approved |
| Phase 4: Domain services | 2 sprints | Phase 3 migrations applied |
| Phase 5: Ledger integration | 1 sprint | Phase 4 commands working |
| Phase 6: API integration | 1 sprint | Phase 5 ledger stable |
| Phase 7: Eventing hardening | 1 sprint | Phase 6 API stable |
| Phase 8: E2E validation | 1 sprint | Phase 7 complete |
| Phase 9: Rollout | 1 sprint | Phase 8 gate approved |