# Phase 2 - Domain Contract and ADR Alignment

Reference artifacts:
- docs/domain-map.md
- docs/adr/0001-app-boundaries.md
- docs/adr/0002-eventing-and-outbox.md
- docs/adr/0003-financial-ledger-invariants.md
- docs/adr/0004-idempotency-and-locking-strategy.md
- docs/adr/0005-api-error-and-idempotency-response-contract.md
- docs/multi-wallet/multi-wallet-phase-tracker.md

## 1. Phase Objective
Define domain contracts and event semantics for multi-wallet features while preserving repository architectural standards.

Phase status target:
- Start: 2026-03-30
- End: **done** (2026-03-30) — domain contracts, lifecycle states, and event contracts complete.

## 2. Scope
In scope:
- Wallet product aggregate contract and lifecycle.
- Sub-wallet lifecycle and transfer semantics.
- Currency config semantics (primary/display-only) and constraints.
- Event catalog additions and idempotency contract alignment.

Out of scope:
- SQL migrations and code implementation.

## 3. Work Breakdown
## Track A: Domain State Machines
1. Define WalletProduct state model.
- Owner: Accounts Domain Team
- Output: allowed transitions and guards.

2. Define SubWallet state and ownership transfer model.
- Owner: Transfers Team
- Output: transfer rules and failure conditions.

3. Define CurrencyConfig mutation rules.
- Owner: Accounts + FX Team
- Output: one-primary invariant and conversion rules.

## Track B: Contract Alignment
1. Define command/query/event contract changes.
- Owner: API Contracts Team
- Output: contract definitions and versioning notes.

2. Confirm idempotency key behavior for new endpoints.
- Owner: Platform Team
- Output: contract-level retry guarantees.

## Track C: ADR Fit Review
1. Validate app-boundary compliance.
- Owner: Architecture
- Output: dependency impact assessment.

2. Validate ledger invariant compatibility.
- Owner: Ledger Team
- Output: invariant conformance report.

## 4. Execution Checklist
- [x] WalletProduct lifecycle documented. → `docs/multi-wallet/deliverables/domain-state-machines.md` § 1
- [x] SubWallet lifecycle and transfer rules documented. → `docs/multi-wallet/deliverables/domain-state-machines.md` § 2
- [x] CurrencyConfig mutation rules documented. → `docs/multi-wallet/deliverables/domain-state-machines.md` § 3
- [x] Command/query/event contract draft completed. → `docs/multi-wallet/deliverables/command-query-event-contracts.md`
- [x] Idempotency and error envelope alignment documented. → `docs/multi-wallet/deliverables/command-query-event-contracts.md` § 5 + `docs/multi-wallet/deliverables/adr-conformance-notes.md` ADR 0004/0005
- [x] App-boundary review completed. → `docs/multi-wallet/deliverables/adr-conformance-notes.md` ADR 0001
- [x] Tracker updated with Phase 2 progress. → `docs/multi-wallet/multi-wallet-phase-tracker.md`

## 5. Verification Checklist
- [x] Domain transitions are deterministic and testable. → State machines have exhaustive guard logic; every transition has guard conditions and error atoms.
- [x] No event ambiguity for transfer/freeze/classification change actions. → 13 new events with distinct names; cascade_source field distinguishes direct vs parent-cascade.
- [x] Contract changes are backward compatible or versioned. → All new events are v1; existing events unchanged. Backward compat resolver defined.
- [x] ADR conformance review approved. → All 5 ADRs pass (docs/multi-wallet/deliverables/adr-conformance-notes.md)

## 6. Exit Criteria
Phase completes only when:
- Domain contracts and state machines are signed off.
- Event and idempotency contracts are approved.
- Phase 3 migration inputs are complete.

## 7. Deliverables
- [x] Domain state machine documentation → `docs/multi-wallet/deliverables/domain-state-machines.md`
- [x] API and event contract addendum → `docs/multi-wallet/deliverables/command-query-event-contracts.md`
- [x] ADR conformance notes → `docs/multi-wallet/deliverables/adr-conformance-notes.md`
- [x] Updated tracker entry → `docs/multi-wallet/multi-wallet-phase-tracker.md`