From 95b0cbca780e1531e46e9358cbc36c48b92e239a Mon Sep 17 00:00:00 2001
From: Matthew Raymer <mraymer@osinetwork.net>
Date: Fri, 29 Aug 2025 11:06:40 +0000
Subject: [PATCH] docs(activeDid): add critical data migration logic to prevent
 data loss

- Add data migration SQL to migration 003 for existing databases
- Automatically copy activeDid from settings table to active_identity table
- Prevent users from losing active identity selection during migration
- Include validation to ensure data exists before migration
- Maintain atomic operation: schema and data migration happen together
- Update risk assessment to reflect data loss prevention
- Add data migration strategy documentation

The migration now safely handles both new and existing databases,
ensuring no user data is lost during the activeDid table separation.
---
 doc/activeDid-migration-plan.md | 37 +++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/doc/activeDid-migration-plan.md b/doc/activeDid-migration-plan.md
index 00803923..14916ff6 100644
--- a/doc/activeDid-migration-plan.md
+++ b/doc/activeDid-migration-plan.md
@@ -99,10 +99,22 @@ Add migration 003 to existing MIGRATIONS array:
 
     -- Insert default record (will be updated during migration)
     INSERT OR IGNORE INTO active_identity (id, activeDid, lastUpdated) VALUES (1, '', datetime('now'));
+
+    -- MIGRATE EXISTING DATA: Copy activeDid from settings to active_identity
+    -- This prevents data loss when migration runs on existing databases
+    UPDATE active_identity
+    SET activeDid = (SELECT activeDid FROM settings WHERE id = 1),
+        lastUpdated = datetime('now')
+    WHERE id = 1
+    AND EXISTS (SELECT 1 FROM settings WHERE id = 1 AND activeDid IS NOT NULL AND activeDid != '');
   `,
 },
 ```
 
+**Critical Data Migration Logic**: This migration includes data transfer to
+prevent users from losing their active identity selection when the migration
+runs on existing databases.
+
 ### **2. Type Definitions**
 
 Create ActiveIdentity interface in `src/db/tables/settings.ts`:
@@ -209,6 +221,22 @@ maintaining compatibility.
 **No changes needed** to the existing migration service - it will continue to
 work with the dual-write pattern.
 
+### **5. Data Migration Strategy**
+
+The migration 003 includes **automatic data migration** to prevent data loss:
+
+1. **Schema Creation**: Creates `active_identity` table with proper constraints
+2. **Data Transfer**: Automatically copies existing `activeDid` from `settings` table
+3. **Validation**: Ensures data exists before attempting migration
+4. **Atomic Operation**: Schema and data migration happen together
+
+**Benefits of Single Migration Approach**:
+
+- **No Data Loss**: Existing users keep their active identity selection
+- **Atomic Operation**: If it fails, nothing is partially migrated
+- **Simpler Tracking**: Only one migration to track and manage
+- **Rollback Safety**: Complete rollback if issues arise
+
 ## What Doesn't Need to Change
 
 - **All Vue components** - API layer handles migration transparently
@@ -274,6 +302,7 @@ No data loss risk - the legacy field continues working unchanged.
 - [ ] Existing IndexedDB migration service continues working
 - [ ] No breaking changes to existing functionality
 - [ ] All platforms tested and verified
+- [ ] Data migration validation successful (existing activeDid data preserved)
 
 ## Risks & Mitigation
 
@@ -281,6 +310,14 @@ No data loss risk - the legacy field continues working unchanged.
 
 - **Mitigation**: Rollback removes new table, legacy system continues working
 - **Impact**: No data loss, no service interruption
+- **Data Safety**: Existing activeDid data is preserved in settings table
+
+### **Low Risk: Data Loss**
+
+- **Mitigation**: Migration 003 includes automatic data transfer from settings
+  to active_identity
+- **Impact**: Users maintain their active identity selection
+- **Validation**: Migration only runs if data exists and is valid
 
 ### **Low Risk: API Changes**