docs: add active identity migration implementation and progress tracking

- Add comprehensive implementation overview document - Track Phase B component migration progress - Document migration strategy and architecture decisions - Include testing and validation procedures Provides complete documentation for the Active Identity table separation migration project.
2025-08-22 10:39:44 +00:00
parent 09e6a7107a
commit 17951d8cb8
2 changed files with 532 additions and 0 deletions
--- a/doc/active-identity-implementation-overview.md
+++ b/doc/active-identity-implementation-overview.md
@@ -0,0 +1,347 @@
+# Active Identity Implementation Overview
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-21T13:40Z
+**Status**: 🚧 **IN PROGRESS** - Implementation Complete, Testing Pending
+
+## Objective
+
+Separate the `activeDid` field from the monolithic `settings` table into a
+dedicated `active_identity` table to achieve:
+
+- **Data normalization** and reduced cache drift
+- **Simplified identity management** with dedicated table
+- **Zero breaking API surface** for existing components
+- **Phased migration** with rollback capability
+
+## Result
+
+This document provides a comprehensive overview of the implemented Active
+Identity table separation system, including architecture, migration strategy,
+and component integration.
+
+## Use/Run
+
+The implementation is ready for testing. Components can immediately use the new
+façade methods while maintaining backward compatibility through dual-write
+triggers.
+
+## Context & Scope
+
+- **Audience**: Developers working with identity management and database
+  migrations
+- **In scope**: Active DID management, database schema evolution, Vue component
+  integration
+- **Out of scope**: Multi-profile support beyond basic scope framework, complex
+  identity hierarchies
+
+## Artifacts & Links
+
+- **Implementation**: `src/db/tables/activeIdentity.ts`,
+  `src/utils/PlatformServiceMixin.ts`
+- **Migrations**: `src/db-sql/migration.ts` (migrations 003 & 004)
+- **Configuration**: `src/config/featureFlags.ts`
+- **Documentation**: This document and progress tracking
+
+## Environment & Preconditions
+
+- **Database**: SQLite (Absurd-SQL for Web, Capacitor SQLite for Mobile)
+- **Framework**: Vue.js with PlatformServiceMixin
+- **Migration System**: Built-in migrationService.ts with automatic execution
+
+## Architecture / Process Overview
+
+The Active Identity separation follows a **phased migration pattern** with
+dual-write triggers to ensure zero downtime and backward compatibility.
+
+```mermaid
+flowchart TD
+    A[Legacy State] --> B[Phase A: Dual-Write]
+    B --> C[Phase B: Component Cutover]
+    C --> D[Phase C: Legacy Cleanup]
+
+    A --> A1[settings.activeDid]
+    B --> B1[active_identity table]
+    B --> B2[Dual-write trigger]
+    B --> B3[Fallback support]
+    C --> C1[Components use façade]
+    C --> C2[Legacy fallback disabled]
+    D --> D1[Drop activeDid column]
+    D --> D2[Remove triggers]
+```
+
+## Interfaces & Contracts
+
+### Database Schema
+
+| Table | Purpose | Key Fields | Constraints |
+|-------|---------|------------|-------------|
+| `active_identity` | Store active DID per scope | `scope`, `active_did`, | Unique scope, FK to accounts.did |
+| | | `updated_at` | |
+| `settings` | User preferences (legacy) | `id`, `accountDid`, `apiServer`, | `activeDid` removed in Phase C |
+| | | etc. | |
+
+### Service Façade API
+
+| Method | Purpose | Parameters | Returns |
+|--------|---------|------------|---------|
+| `$getActiveDid(scope?)` | Retrieve active DID | `scope` (default: | `Promise<string \| null>` |
+| | | 'default') | |
+| `$setActiveDid(did, scope?)` | Set active DID | `did`, `scope` (default: | `Promise<void>` |
+| | | 'default') | |
+| `$switchActiveIdentity(did)` | Switch to different DID | `did` | `Promise<void>` |
+| `$getActiveIdentityScopes()` | Get available scopes | None | `Promise<string[]>` |
+
+## Repro: End-to-End Procedure
+
+### 1. Database Migration Execution
+
+```bash
+# Migrations run automatically on app startup
+# Migration 003: Creates active_identity table
+# Migration 004: Drops settings.activeDid column (Phase C)
+```
+
+### 2. Component Usage
+
+```typescript
+// Before (legacy)
+const activeDid = settings.activeDid || "";
+await this.$saveSettings({ activeDid: newDid });
+
+// After (new façade)
+const activeDid = await this.$getActiveDid() || "";
+await this.$setActiveDid(newDid);
+```
+
+### 3. Feature Flag Control
+
+```typescript
+// Enable/disable migration phases
+FLAGS.USE_ACTIVE_IDENTITY_ONLY = false;      // Allow legacy fallback
+FLAGS.DROP_SETTINGS_ACTIVEDID = false;       // Keep legacy column
+FLAGS.LOG_ACTIVE_ID_FALLBACK = true;         // Log fallback usage
+```
+
+## What Works (Evidence)
+
+- ✅ **Migration Infrastructure**: Migrations 003 and 004 integrated into
+  `migrationService.ts`
+- ✅ **Table Creation**: `active_identity` table schema with proper constraints
+  and indexes
+- ✅ **Service Façade**: PlatformServiceMixin extended with all required methods
+- ✅ **Feature Flags**: Comprehensive flag system for controlling rollout phases
+- ✅ **Dual-Write Support**: One-way trigger from `settings.activeDid` →
+  `active_identity.active_did`
+- ✅ **Validation**: DID existence validation before setting as active
+- ✅ **Error Handling**: Comprehensive error handling with logging
+
+## What Doesn't (Evidence & Hypotheses)
+
+- ❌ **Component Migration**: No components yet updated to use new façade
+  methods
+- ❌ **Testing**: No automated tests for new functionality
+- ❌ **Performance Validation**: No benchmarks for read/write performance
+- ❌ **Cross-Platform Validation**: Not tested on mobile platforms yet
+
+## Risks, Limits, Assumptions
+
+### **Migration Risks**
+
+- **Data Loss**: If migration fails mid-process, could lose active DID state
+- **Rollback Complexity**: Phase C (column drop) requires table rebuild, not
+  easily reversible
+- **Trigger Dependencies**: Dual-write trigger could fail if `active_identity`
+  table is corrupted
+
+### **Performance Limits**
+
+- **Dual-Write Overhead**: Each `activeDid` change triggers additional
+  database operations
+- **Fallback Queries**: Legacy fallback requires additional database queries
+- **Transaction Scope**: Active DID changes wrapped in transactions for
+  consistency
+
+### **Security Boundaries**
+
+- **DID Validation**: Only validates DID exists in accounts table, not
+  ownership
+- **Scope Isolation**: No current scope separation enforcement beyond table
+  constraints
+- **Access Control**: No row-level security on `active_identity` table
+
+## Next Steps
+
+| Owner | Task | Exit Criteria | Target Date (UTC) |
+|-------|------|---------------|-------------------|
+| Developer | Test migrations | Migrations execute without errors | 2025-08-21 |
+| Developer | Update components | All components use new façade | 2025-08-22 |
+| | | methods | |
+| Developer | Performance testing | Read/write performance meets | 2025-08-23 |
+| | | requirements | |
+| Developer | Phase C activation | Feature flag enables column | 2025-08-24 |
+| | | removal | |
+
+## References
+
+- [Database Migration Guide](../database-migration-guide.md)
+- [PlatformServiceMixin Documentation](../component-communication-guide.md)
+- [Feature Flags Configuration](../feature-flags.md)
+
+## Competence Hooks
+
+- **Why this works**: Phased migration with dual-write triggers ensures zero
+  downtime while maintaining data consistency through foreign key constraints
+  and validation
+- **Common pitfalls**: Forgetting to update components before enabling
+  `USE_ACTIVE_IDENTITY_ONLY`, not testing rollback scenarios, ignoring
+  cross-platform compatibility
+- **Next skill unlock**: Implement automated component migration using codemods
+  and ESLint rules
+- **Teach-back**: Explain how the dual-write trigger prevents data divergence
+  during the transition phase
+
+## Collaboration Hooks
+
+- **Reviewers**: Database team for migration logic, Vue team for component
+  integration, DevOps for deployment strategy
+- **Sign-off checklist**: Migrations tested in staging, components updated,
+  performance validated, rollback plan documented
+
+## Assumptions & Limits
+
+- **Single User Focus**: Current implementation assumes single-user mode with
+  'default' scope
+- **Vue Compatibility**: Assumes `vue-facing-decorator` compatibility (needs
+  validation)
+- **Migration Timing**: Assumes migrations run on app startup (automatic
+  execution)
+- **Platform Support**: Assumes same behavior across Web (Absurd-SQL) and
+  Mobile (Capacitor SQLite)
+
+## Implementation Details
+
+### **Migration 003: Table Creation**
+
+Creates the `active_identity` table with:
+
+- **Primary Key**: Auto-incrementing ID
+- **Scope Field**: For future multi-profile support (currently 'default')
+- **Active DID**: Foreign key to accounts.did with CASCADE UPDATE
+- **Timestamps**: ISO format timestamps for audit trail
+- **Indexes**: Performance optimization for scope and DID lookups
+
+### **Migration 004: Column Removal**
+
+Implements Phase C by:
+
+- **Table Rebuild**: Creates new settings table without activeDid column
+- **Data Preservation**: Copies all other data from legacy table
+- **Index Recreation**: Rebuilds necessary indexes
+- **Trigger Cleanup**: Removes dual-write triggers
+
+### **Service Façade Implementation**
+
+The PlatformServiceMixin extension provides:
+
+- **Dual-Read Logic**: Prefers new table, falls back to legacy during
+  transition
+- **Dual-Write Logic**: Updates both tables during Phase A/B
+- **Validation**: Ensures DID exists before setting as active
+- **Transaction Safety**: Wraps operations in database transactions
+- **Error Handling**: Comprehensive logging and error propagation
+
+### **Feature Flag System**
+
+Controls migration phases through:
+
+- **`USE_ACTIVE_IDENTITY_ONLY`**: Disables legacy fallback reads
+- **`DROP_SETTINGS_ACTIVEDID`**: Enables Phase C column removal
+- **`LOG_ACTIVE_ID_FALLBACK`**: Logs when legacy fallback is used
+- **`ENABLE_ACTIVE_IDENTITY_MIGRATION`**: Master switch for migration
+  system
+
+## Security Considerations
+
+### **Data Validation**
+
+- DID format validation (basic "did:" prefix check)
+- Foreign key constraints ensure referential integrity
+- Transaction wrapping prevents partial updates
+
+### **Access Control**
+
+- No row-level security implemented
+- Scope isolation framework in place for future use
+- Validation prevents setting non-existent DIDs as active
+
+### **Audit Trail**
+
+- Timestamps on all active identity changes
+- Logging of fallback usage and errors
+- Migration tracking through built-in system
+
+## Performance Characteristics
+
+### **Read Operations**
+
+- **Primary Path**: Single query to `active_identity` table
+- **Fallback Path**: Additional query to `settings` table (Phase A only)
+- **Indexed Fields**: Both scope and active_did are indexed
+
+### **Write Operations**
+
+- **Dual-Write**: Updates both tables during transition (Phase A/B)
+- **Transaction Overhead**: All operations wrapped in transactions
+- **Trigger Execution**: Additional database operations per update
+
+### **Migration Impact**
+
+- **Table Creation**: Minimal impact (runs once)
+- **Column Removal**: Moderate impact (table rebuild required)
+- **Data Seeding**: Depends on existing data volume
+
+## Testing Strategy
+
+### **Unit Testing**
+
+- Service façade method validation
+- Error handling and edge cases
+- Transaction rollback scenarios
+
+### **Integration Testing**
+
+- Migration execution and rollback
+- Cross-platform compatibility
+- Performance under load
+
+### **End-to-End Testing**
+
+- Component integration
+- User workflow validation
+- Migration scenarios
+
+## Deployment Considerations
+
+### **Rollout Strategy**
+
+- **Phase A**: Deploy with dual-write enabled
+- **Phase B**: Update components to use new methods
+- **Phase C**: Enable column removal (irreversible)
+
+### **Rollback Plan**
+
+- **Phase A/B**: Disable feature flags, revert to legacy methods
+- **Phase C**: Requires database restore (no automatic rollback)
+
+### **Monitoring**
+
+- Track fallback usage through logging
+- Monitor migration success rates
+- Alert on validation failures
+
+---
+
+**Status**: Implementation complete, ready for testing and component migration
+**Next Review**: After initial testing and component updates
+**Maintainer**: Development team
--- a/doc/active-identity-phase-b-progress.md
+++ b/doc/active-identity-phase-b-progress.md
@@ -0,0 +1,185 @@
+# Active Identity Migration - Phase B Progress
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-22T07:05Z
+**Status**: 🚧 **IN PROGRESS** - Component Migration Active
+
+## Objective
+
+Complete **Phase B: Component Cutover** by updating all Vue components to use the new Active Identity façade methods instead of directly accessing `settings.activeDid`.
+
+## Current Status
+
+### ✅ **Completed**
+- **Migration Infrastructure**: Migrations 003 and 004 implemented
+- **Service Façade**: PlatformServiceMixin extended with all required methods
+- **TypeScript Types**: Added missing method declarations to Vue component interfaces
+- **Feature Flags**: Comprehensive flag system for controlling rollout phases
+
+### 🔄 **In Progress**
+- **Component Migration**: Manually updating critical components
+- **Pattern Establishment**: Creating consistent migration approach
+
+### ❌ **Pending**
+- **Bulk Component Updates**: 40+ components need migration
+- **Testing**: Validate migrated components work correctly
+- **Performance Validation**: Ensure no performance regressions
+
+## Migration Progress
+
+### **Components Migrated (3/40+)**
+
+| Component | Status | Changes Made | Notes |
+|-----------|--------|--------------|-------|
+| `IdentitySwitcherView.vue` | ✅ Complete | - Updated `switchIdentity()` method<br>- Added FLAGS import<br>- Uses `$setActiveDid()` | Critical component for identity switching |
+| `ImportDerivedAccountView.vue` | ✅ Complete | - Updated `incrementDerivation()` method<br>- Added FLAGS import<br>- Uses `$setActiveDid()` | Handles new account creation |
+| `ClaimAddRawView.vue` | ✅ Complete | - Updated `initializeSettings()` method<br>- Uses `$getActiveDid()` | Reads active DID for claims |
+
+### **Components Pending Migration (37+)**
+
+| Component | Usage Pattern | Priority | Estimated Effort |
+|-----------|---------------|----------|------------------|
+| `HomeView.vue` | ✅ Updated | High | 5 min |
+| `ProjectsView.vue` | `settings.activeDid \|\| ""` | High | 3 min |
+| `ContactsView.vue` | `settings.activeDid \|\| ""` | High | 3 min |
+| `AccountViewView.vue` | `settings.activeDid \|\| ""` | High | 3 min |
+| `InviteOneView.vue` | `settings.activeDid \|\| ""` | Medium | 3 min |
+| `TestView.vue` | `settings.activeDid \|\| ""` | Medium | 3 min |
+| `SeedBackupView.vue` | `settings.activeDid \|\| ""` | Medium | 3 min |
+| `QuickActionBvcBeginView.vue` | `const activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `ConfirmGiftView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `ClaimReportCertificateView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `ImportAccountView.vue` | `settings.activeDid,` | Medium | 3 min |
+| `MembersList.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `ShareMyContactInfoView.vue` | `const activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `ClaimView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `ImageMethodDialog.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `DiscoverView.vue` | `settings.activeDid as string` | Medium | 3 min |
+| `QuickActionBvcEndView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `ContactQRScanFullView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `ContactGiftingView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `OfferDetailsView.vue` | `this.activeDid = settings.activeDid ?? ""` | Medium | 3 min |
+| `NewActivityView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `OfferDialog.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `SharedPhotoView.vue` | `this.activeDid = settings.activeDid` | Medium | 3 min |
+| `ContactQRScanShowView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `NewEditProjectView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `GiftedDialog.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `HelpView.vue` | `if (settings.activeDid)` | Medium | 3 min |
+| `TopMessage.vue` | `settings.activeDid?.slice(11, 15)` | Medium | 3 min |
+| `ClaimCertificateView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `UserProfileView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `OnboardingDialog.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `RecentOffersToUserView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `RecentOffersToUserProjectsView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `ContactImportView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+| `GiftedDetailsView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
+
+## Migration Patterns
+
+### **Pattern 1: Simple Read Replacement**
+```typescript
+// Before
+this.activeDid = settings.activeDid || "";
+
+// After
+this.activeDid = await this.$getActiveDid() || "";
+```
+
+### **Pattern 2: Write Replacement with Dual-Write**
+```typescript
+// Before
+await this.$saveSettings({ activeDid: newDid });
+
+// After
+await this.$setActiveDid(newDid);
+
+// Legacy fallback - remove after Phase C
+if (!FLAGS.USE_ACTIVE_IDENTITY_ONLY) {
+  await this.$saveSettings({ activeDid: newDid });
+}
+```
+
+### **Pattern 3: FLAGS Import Addition**
+```typescript
+// Add to imports section
+import { FLAGS } from "@/config/featureFlags";
+```
+
+## Next Steps
+
+### **Immediate Actions (Next 30 minutes)**
+1. **Complete High-Priority Components**: Update remaining critical components
+2. **Test Migration**: Verify migrated components work correctly
+3. **Run Linter**: Check for any remaining TypeScript issues
+
+### **Short Term (Next 2 hours)**
+1. **Bulk Migration**: Use automated script for remaining components
+2. **Testing**: Validate all migrated components
+3. **Performance Check**: Ensure no performance regressions
+
+### **Medium Term (Next 1 day)**
+1. **Phase C Preparation**: Enable `USE_ACTIVE_IDENTITY_ONLY` flag
+2. **Legacy Fallback Removal**: Remove dual-write patterns
+3. **Final Testing**: End-to-end validation
+
+## Success Criteria
+
+### **Phase B Complete When**
+- [ ] All 40+ components use new façade methods
+- [ ] No direct `settings.activeDid` access remains
+- [ ] All components pass linting
+- [ ] Basic functionality tested and working
+- [ ] Performance maintained or improved
+
+### **Phase C Ready When**
+- [ ] All components migrated and tested
+- [ ] Feature flag `USE_ACTIVE_IDENTITY_ONLY` can be enabled
+- [ ] No legacy fallback usage in production
+- [ ] Performance benchmarks show improvement
+
+## Risks & Mitigation
+
+### **High Risk**
+- **Component Breakage**: Test each migrated component individually
+- **Performance Regression**: Monitor performance metrics during migration
+- **TypeScript Errors**: Ensure all method signatures are properly declared
+
+### **Medium Risk**
+- **Migration Inconsistency**: Use consistent patterns across all components
+- **Testing Coverage**: Ensure comprehensive testing of identity switching flows
+
+### **Low Risk**
+- **Backup Size**: Minimal backup strategy for critical files only
+- **Rollback Complexity**: Simple git revert if needed
+
+## Tools & Scripts
+
+### **Migration Scripts**
+- `scripts/migrate-active-identity-components.sh` - Full backup version
+- `scripts/migrate-active-identity-components-efficient.sh` - Minimal backup version
+
+### **Testing Commands**
+```bash
+# Check for remaining settings.activeDid usage
+grep -r "settings\.activeDid" src/views/ src/components/
+
+# Run linter
+npm run lint-fix
+
+# Test specific component
+npm run test:web -- --grep "IdentitySwitcher"
+```
+
+## References
+
+- [Active Identity Implementation Overview](./active-identity-implementation-overview.md)
+- [PlatformServiceMixin Documentation](../component-communication-guide.md)
+- [Feature Flags Configuration](../feature-flags.md)
+- [Database Migration Guide](../database-migration-guide.md)
+
+---
+
+**Status**: Phase B in progress, 3/40+ components migrated
+**Next Review**: After completing high-priority components
+**Maintainer**: Development team