android-sdd 1.0.0

package/skills/Data Layer/Merge Strategy/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: merge-strategy
+description: >
+  Merge strategies for combining local and remote data changes in Android.
+  Load this skill when syncing collections, merging list changes,
+  handling additions/deletions on both sides, or implementing CRDT-like patterns.
+---
+
+# Merge Strategy
+
+## Overview
+
+A merge strategy defines how to combine two diverged versions of a dataset into a single consistent result. This is more complex than single-record conflict resolution — it handles collections where both sides may have added, modified, and deleted different items.
+
+---
+
+## Core Principles
+
+- Merging requires knowledge of the **base state** — the last known common version
+- Track **deletions explicitly** — a missing item could mean "deleted" or "not yet synced"
+- Use **stable IDs** as the merge key — never use position or timestamp alone
+- Make merge operations **idempotent** — running merge twice yields the same result
+- Prefer **additive merges** where possible — deletions are the hardest case
+
+---
+
+## Collection Merge Patterns
+
+### Pattern 1: Remote-Authoritative List Merge
+
+```kotlin
+// ✅ Server is source of truth for the list — local additions queued for push
+fun mergeUserList(
+    localItems: List<UserEntity>,
+    remoteItems: List<UserDto>,
+    pendingLocalCreates: List<UserEntity>
+): List<UserEntity> {
+    val remoteById = remoteItems.associateBy { it.id }
+    val localById = localItems.associateBy { it.id }
+
+    val merged = mutableListOf<UserEntity>()
+
+    // Add all remote items (authoritative)
+    remoteItems.forEach { remote ->
+        val local = localById[remote.id]
+        merged.add(
+            if (local != null && local.updatedAt > remote.updatedAt) {
+                local  // local is newer — keep, will push
+            } else {
+                remote.toEntity()  // remote wins
+            }
+        )
+    }
+
+    // Add local-only creates (not yet on server)
+    pendingLocalCreates
+        .filter { it.id !in remoteById }
+        .forEach { merged.add(it) }
+
+    return merged
+}
+```
+
+---
+
+### Pattern 2: Three-Way Collection Merge
+
+```kotlin
+// ✅ Three-way merge — base + local + remote
+data class CollectionDiff<T>(
+    val added: List<T>,
+    val modified: List<T>,
+    val deleted: List<String>  // IDs
+)
+
+fun <T : HasId> threeWayMerge(
+    base: List<T>,
+    local: List<T>,
+    remote: List<T>
+): List<T> {
+    val baseIds = base.map { it.id }.toSet()
+    val localIds = local.map { it.id }.toSet()
+    val remoteIds = remote.map { it.id }.toSet()
+
+    val baseById   = base.associateBy { it.id }
+    val localById  = local.associateBy { it.id }
+    val remoteById = remote.associateBy { it.id }
+
+    val result = mutableListOf<T>()
+
+    // Items present in remote
+    remoteIds.forEach { id ->
+        val remoteItem = remoteById[id]!!
+        val localItem  = localById[id]
+        val baseItem   = baseById[id]
+
+        when {
+            // New on remote — add
+            id !in baseIds -> result.add(remoteItem)
+
+            // Deleted locally — don't add (local delete wins)
+            id !in localIds -> { /* skip — locally deleted */ }
+
+            // Modified on both sides — resolve conflict
+            localItem != baseItem && remoteItem != baseItem ->
+                result.add(resolveFieldConflict(localItem!!, remoteItem))
+
+            // Only local changed
+            localItem != baseItem -> result.add(localItem!!)
+
+            // Only remote changed, or neither changed
+            else -> result.add(remoteItem)
+        }
+    }
+
+    // Items added locally (not on remote or base)
+    localIds
+        .filter { it !in baseIds && it !in remoteIds }
+        .forEach { result.add(localById[it]!!) }
+
+    return result
+}
+
+interface HasId {
+    val id: String
+}
+```
+
+---
+
+### Pattern 3: Additive-Only Merge (No Deletions)
+
+```kotlin
+// ✅ Simplest merge — items are never deleted, only added
+// Use for: event logs, audit trails, append-only feeds
+
+fun <T : HasId> additiveMerge(
+    local: List<T>,
+    remote: List<T>
+): List<T> {
+    val localById = local.associateBy { it.id }
+    val remoteById = remote.associateBy { it.id }
+
+    // Union of both sets — remote wins on conflict
+    return (localById + remoteById).values.toList()
+}
+```
+
+---
+
+### Pattern 4: Timestamp-Based List Merge
+
+```kotlin
+// ✅ Each item has a timestamp — most recent version of each ID wins
+data class TimestampedItem<T>(val id: String, val data: T, val updatedAt: Long)
+
+fun <T> timestampMerge(
+    local: List<TimestampedItem<T>>,
+    remote: List<TimestampedItem<T>>,
+    deletedRemoteIds: Set<String> = emptySet()
+): List<TimestampedItem<T>> {
+    val merged = (local + remote)
+        .groupBy { it.id }
+        .mapValues { (_, versions) -> versions.maxByOrNull { it.updatedAt }!! }
+        .values
+        .filter { it.id !in deletedRemoteIds }
+        .toList()
+
+    return merged
+}
+```
+
+---
+
+## Tracking Deletions
+
+```kotlin
+// ✅ Server must provide a tombstone/deleted list
+// Without this, you can't distinguish "deleted" from "not synced yet"
+
+@Serializable
+data class SyncResponseDto(
+    val updated: List<UserDto>,
+    val deletedIds: List<String>,  // explicit deletions
+    val syncToken: String          // cursor for next delta sync
+)
+
+// ✅ Apply deletions explicitly
+suspend fun applySync(response: SyncResponseDto) {
+    db.withTransaction {
+        // Apply updates/additions
+        userDao.upsertAll(response.updated.map { it.toEntity() })
+        // Apply deletions
+        userDao.deleteByIds(response.deletedIds)
+        // Save sync cursor
+        prefs.saveSyncToken(response.syncToken)
+    }
+}
+```
+
+---
+
+## CRDT-Inspired Patterns
+
+```kotlin
+// ✅ Grow-only Set (G-Set) — items can only be added, never removed
+// Use for: tags, labels, read receipts
+
+class GrowOnlySet<T>(private val items: MutableSet<T> = mutableSetOf()) {
+    fun add(item: T) { items.add(item) }
+    fun merge(other: GrowOnlySet<T>): GrowOnlySet<T> =
+        GrowOnlySet((items + other.items).toMutableSet())
+    fun contains(item: T) = items.contains(item)
+}
+
+// ✅ Last-Write-Wins Register (LWW-Register) — per-field versioning
+data class LWWRegister<T>(val value: T, val timestamp: Long) {
+    fun merge(other: LWWRegister<T>): LWWRegister<T> =
+        if (other.timestamp > timestamp) other else this
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Replacing the entire local list with remote on every sync — loses local changes
+- No tombstones for deletions — deleted items reappear after sync
+- Using list position as merge key — positions shift, wrong items merged
+- Merging without a base state — can't distinguish add from conflict
+- Merging on the main thread — use Dispatchers.IO for large collections
+
+---
+
+## Related Skills
+
+- `conflict-resolution` — single-record conflict handling
+- `sync-engine` — orchestrating full sync with merge
+- `room` — persisting merged results
+- `dto-mapping` — mapping remote items for merge

package/skills/Data Layer/Migration/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: migration
+description: >
+  Room database migration — writing, testing, and managing schema changes.
+  Load this skill when changing the database schema (add/remove column or table,
+  change type), writing Migration objects, or testing migrations.
+---
+
+# Migration
+
+## Overview
+A migration defines how to transform the database schema from one version to the next without losing user data. Room requires a migration path for every version increment. Missing migrations cause a crash at startup — Room detects the schema mismatch and throws an `IllegalStateException`.
+
+---
+
+## Core Principles
+
+- **Never use `fallbackToDestructiveMigration()`** in production — it deletes all user data
+- Always export schema (`exportSchema = true`) — required for writing correct migrations
+- Write a migration for **every version increment** — even if only one table changed
+- **Test every migration** — automated migration tests catch silent data corruption
+- Keep migration SQL simple — complex logic belongs in a one-time data migration job
+
+---
+
+## Version Increment Workflow
+
+```
+1. Change @Entity — add/remove/rename column or table
+2. Increment version in @Database
+3. Write Migration(oldVersion, newVersion)
+4. Add migration to RoomDatabase builder
+5. Export schema and commit schemas/ directory
+6. Write migration test
+```
+
+---
+
+## Writing Migrations
+
+```kotlin
+// ✅ Add a column
+val MIGRATION_1_2 = object : Migration(1, 2) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        database.execSQL(
+            "ALTER TABLE users ADD COLUMN phone_number TEXT"
+        )
+    }
+}
+
+// ✅ Add a column with default value
+val MIGRATION_2_3 = object : Migration(2, 3) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        database.execSQL(
+            "ALTER TABLE users ADD COLUMN status TEXT NOT NULL DEFAULT 'active'"
+        )
+    }
+}
+
+// ✅ Add a new table
+val MIGRATION_3_4 = object : Migration(3, 4) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        database.execSQL("""
+            CREATE TABLE IF NOT EXISTS orders (
+                id TEXT NOT NULL PRIMARY KEY,
+                user_id TEXT NOT NULL,
+                total INTEGER NOT NULL,
+                created_at INTEGER NOT NULL,
+                FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+            )
+        """)
+        database.execSQL(
+            "CREATE INDEX IF NOT EXISTS index_orders_user_id ON orders(user_id)"
+        )
+    }
+}
+
+// ✅ Rename a column (SQLite doesn't support RENAME COLUMN before API 29)
+val MIGRATION_4_5 = object : Migration(4, 5) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        // Create new table with correct schema
+        database.execSQL("""
+            CREATE TABLE users_new (
+                id TEXT NOT NULL PRIMARY KEY,
+                full_name TEXT NOT NULL,
+                email TEXT NOT NULL
+            )
+        """)
+        // Copy data
+        database.execSQL("""
+            INSERT INTO users_new (id, full_name, email)
+            SELECT id, name, email FROM users
+        """)
+        // Drop old table
+        database.execSQL("DROP TABLE users")
+        // Rename new table
+        database.execSQL("ALTER TABLE users_new RENAME TO users")
+    }
+}
+
+// ✅ Drop a column (same approach — recreate table)
+val MIGRATION_5_6 = object : Migration(5, 6) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        database.execSQL("""
+            CREATE TABLE users_new (
+                id TEXT NOT NULL PRIMARY KEY,
+                full_name TEXT NOT NULL
+                -- removed: phone_number
+            )
+        """)
+        database.execSQL("INSERT INTO users_new SELECT id, full_name FROM users")
+        database.execSQL("DROP TABLE users")
+        database.execSQL("ALTER TABLE users_new RENAME TO users")
+    }
+}
+```
+
+---
+
+## Registering Migrations
+
+```kotlin
+// ✅ Register all migrations in database builder
+@Module
+@InstallIn(SingletonComponent::class)
+object DatabaseModule {
+
+    @Provides
+    @Singleton
+    fun provideDatabase(@ApplicationContext context: Context): AppDatabase =
+        Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
+            .addMigrations(
+                MIGRATION_1_2,
+                MIGRATION_2_3,
+                MIGRATION_3_4,
+                MIGRATION_4_5,
+                MIGRATION_5_6
+            )
+            .build()
+}
+```
+
+---
+
+## Auto Migration (Room 2.4+)
+
+```kotlin
+// ✅ For simple schema changes — Room generates migration automatically
+@Database(
+    entities = [UserEntity::class],
+    version = 3,
+    exportSchema = true,
+    autoMigrations = [
+        AutoMigration(from = 1, to = 2),  // simple add column — auto-generated
+        AutoMigration(from = 2, to = 3, spec = Migration2To3::class)  // with rename
+    ]
+)
+abstract class AppDatabase : RoomDatabase()
+
+// ✅ AutoMigrationSpec — for rename/delete (needs disambiguation)
+@RenameColumn(tableName = "users", fromColumnName = "name", toColumnName = "full_name")
+class Migration2To3 : AutoMigrationSpec
+```
+
+---
+
+## Testing Migrations
+
+```kotlin
+// ✅ MigrationTestHelper — test each migration
+@RunWith(AndroidJUnit4::class)
+class MigrationTest {
+
+    @get:Rule
+    val helper = MigrationTestHelper(
+        InstrumentationRegistry.getInstrumentation(),
+        AppDatabase::class.java
+    )
+
+    @Test
+    fun migrate1To2() {
+        // Create version 1 database
+        helper.createDatabase(TEST_DB, 1).apply {
+            execSQL("INSERT INTO users VALUES ('1', 'Ali')")
+            close()
+        }
+
+        // Run migration
+        val db = helper.runMigrationsAndValidate(TEST_DB, 2, true, MIGRATION_1_2)
+
+        // Verify data integrity
+        val cursor = db.query("SELECT * FROM users WHERE id = '1'")
+        assertTrue(cursor.moveToFirst())
+        assertEquals("Ali", cursor.getString(cursor.getColumnIndex("full_name")))
+        // new column exists with default value
+        assertNotNull(cursor.getString(cursor.getColumnIndex("phone_number")))
+        cursor.close()
+    }
+
+    companion object {
+        private const val TEST_DB = "migration_test"
+    }
+}
+```
+
+---
+
+## Multi-Step Migration Path
+
+```kotlin
+// ✅ Room applies migrations sequentially — 1→2→3→4 not 1→4
+// All intermediate migrations must be present
+
+// If user has version 1, Room applies:
+// MIGRATION_1_2, then MIGRATION_2_3, then MIGRATION_3_4
+
+// ✅ Multi-version single migration (skip versions)
+val MIGRATION_1_4 = object : Migration(1, 4) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        // Apply all changes from 1→4 in one step
+        // Only needed if you want to optimize multi-version upgrades
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- `fallbackToDestructiveMigration()` in production — deletes all user data
+- Not exporting schema (`exportSchema = false`) — can't write correct migrations
+- Running data transformations in migration SQL — use a one-time WorkManager job instead
+- Not committing `schemas/` directory to version control — migration tests require it
+- Incrementing version without writing migration — crashes on existing installs
+- Writing migration without a test — silent data corruption risk
+
+---
+
+## Related Skills
+- `room` — Room database setup
+- `dao` — DAO queries after schema changes
+- `database-versioning-strategy` — when and how to version the schema
+- `workmanager` — one-time data migration jobs after schema change