@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.1

package/pipeline/skills/shared/external/room-database/SKILL.md

@@ -8,6 +8,11 @@ description: "Implement Room database persistence on Android with @Entity, @Dao,
 Room persistence library patterns for Android targeting Room 2.6+ with
 KSP, Kotlin coroutines, and Flow-based reactive queries.
 
+Detailed, copy-ready code for every section below lives in
+[references/patterns.md](references/patterns.md). Load that file when you need a
+full example to adapt (entity, DAO, migration, Hilt module, or a test). Each
+heading there mirrors a section here.
+
 ## Contents
 
 - [Entity Definition](#entity-definition)
@@ -18,6 +23,9 @@ KSP, Kotlin coroutines, and Flow-based reactive queries.
 - [Relations](#relations)
 - [Migration Strategies](#migration-strategies)
 - [Hilt Integration](#hilt-integration)
+- [Encrypted Database (SQLCipher)](#encrypted-database-sqlcipher)
+- [Async Database Provisioning](#async-database-provisioning)
+- [Runtime Hygiene](#runtime-hygiene)
 - [Testing with In-Memory Database](#testing-with-in-memory-database)
 - [Do's and Don'ts](#dos-and-donts)
 - [Troubleshooting](#troubleshooting)
@@ -25,107 +33,22 @@ KSP, Kotlin coroutines, and Flow-based reactive queries.
 
 ## Entity Definition
 
-```kotlin
-@Entity(
-    tableName = "flights",
-    indices = [
-        Index(value = ["origin_code", "destination_code"]),
-        Index(value = ["departure_time"]),
-    ],
-)
-data class FlightEntity(
-    @PrimaryKey
-    val id: String,
-    @ColumnInfo(name = "origin_code")
-    val originCode: String,
-    @ColumnInfo(name = "origin_name")
-    val originName: String,
-    @ColumnInfo(name = "destination_code")
-    val destinationCode: String,
-    @ColumnInfo(name = "destination_name")
-    val destinationName: String,
-    @ColumnInfo(name = "departure_time")
-    val departureTime: String,
-    @ColumnInfo(name = "arrival_time")
-    val arrivalTime: String,
-    @ColumnInfo(name = "price_amount")
-    val priceAmount: Double,
-    @ColumnInfo(name = "price_currency")
-    val priceCurrency: String,
-    val status: String,
-    @ColumnInfo(name = "updated_at", defaultValue = "0")
-    val updatedAt: Long = System.currentTimeMillis(),
-)
-```
-
-### Composite Primary Key
+Annotate a `data class` with `@Entity(tableName = ...)`. Declare a `@PrimaryKey`,
+map snake_case columns with `@ColumnInfo(name = ...)`, and add `indices` for
+columns that appear in `WHERE`/`ORDER BY`. Use `primaryKeys = [...]` on the
+entity for a composite key instead of `@PrimaryKey`.
 
-```kotlin
-@Entity(
-    tableName = "booking_passengers",
-    primaryKeys = ["booking_id", "passenger_id"],
-)
-data class BookingPassengerEntity(
-    @ColumnInfo(name = "booking_id")
-    val bookingId: String,
-    @ColumnInfo(name = "passenger_id")
-    val passengerId: String,
-    @ColumnInfo(name = "seat_number")
-    val seatNumber: String?,
-)
-```
+See [references/patterns.md#entity-definition](references/patterns.md#entity-definition)
+for a full entity and a composite-key entity.
 
 ## DAO Interface
 
-```kotlin
-@Dao
-interface FlightDao {
-
-    @Query("SELECT * FROM flights WHERE origin_code = :origin AND destination_code = :destination ORDER BY departure_time ASC")
-    fun getFlights(origin: String, destination: String): Flow<List<FlightEntity>>
-
-    @Query("SELECT * FROM flights WHERE id = :id")
-    fun getFlightById(id: String): Flow<FlightEntity?>
-
-    @Query("SELECT * FROM flights WHERE id = :id")
-    suspend fun getFlightByIdOnce(id: String): FlightEntity?
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun insertFlight(flight: FlightEntity)
+Mark the interface `@Dao`. Return `Flow<T>` for reactive reads and `suspend`
+for one-shot reads/writes. Use `@Query`, `@Insert`, `@Update`, `@Delete`,
+`@Upsert`, and wrap multi-statement operations in a `@Transaction` default
+method.
 
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun insertFlights(flights: List<FlightEntity>)
-
-    @Upsert
-    suspend fun upsertFlights(flights: List<FlightEntity>)
-
-    @Update
-    suspend fun updateFlight(flight: FlightEntity)
-
-    @Delete
-    suspend fun deleteFlight(flight: FlightEntity)
-
-    @Query("DELETE FROM flights WHERE id = :id")
-    suspend fun deleteFlightById(id: String)
-
-    @Query("DELETE FROM flights WHERE updated_at < :threshold")
-    suspend fun deleteStaleFlights(threshold: Long)
-
-    @Query("SELECT COUNT(*) FROM flights")
-    fun getFlightCount(): Flow<Int>
-
-    @Transaction
-    suspend fun replaceAllFlights(flights: List<FlightEntity>) {
-        deleteAllFlights()
-        insertFlights(flights)
-    }
-
-    @Query("DELETE FROM flights")
-    suspend fun deleteAllFlights()
-}
-```
-
-### @Upsert vs @Insert(onConflict = REPLACE)
+Pick the write strategy by intent:
 
 | Strategy | Behavior | Use When |
 |----------|----------|----------|
@@ -133,30 +56,13 @@ interface FlightDao {
 | `@Insert(REPLACE)` | Delete + re-insert on conflict | Simpler; triggers delete cascade |
 | `@Insert(IGNORE)` | Skip on conflict | Inserting if not exists, no update needed |
 
-## Database Setup
+Full DAO surface: [references/patterns.md#dao-interface](references/patterns.md#dao-interface).
 
-```kotlin
-@Database(
-    entities = [
-        FlightEntity::class,
-        BookingEntity::class,
-        BookingPassengerEntity::class,
-    ],
-    version = 2,
-    autoMigrations = [
-        AutoMigration(from = 1, to = 2),
-    ],
-    exportSchema = true,
-)
-@TypeConverters(Converters::class)
-abstract class AppDatabase : RoomDatabase() {
-    abstract fun flightDao(): FlightDao
-    abstract fun bookingDao(): BookingDao
-}
-```
+## Database Setup
 
-Always set `exportSchema = true` and configure the schema export directory in
-`build.gradle.kts`:
+Declare an `abstract class ... : RoomDatabase()` with `@Database(entities, version)`,
+one abstract accessor per DAO, and `@TypeConverters` when needed. Always set
+`exportSchema = true` and point KSP at a schema directory:
 
 ```kotlin
 ksp {
@@ -164,357 +70,103 @@ ksp {
 }
 ```
 
-## Reactive Queries with Flow
-
-DAO methods returning `Flow` automatically emit new values when the underlying
-table changes.
+Full `@Database` declaration:
+[references/patterns.md#database-setup](references/patterns.md#database-setup).
 
-```kotlin
-// DAO returns Flow
-@Query("SELECT * FROM flights WHERE origin_code = :origin")
-fun getFlightsByOrigin(origin: String): Flow<List<FlightEntity>>
-
-// Repository maps to domain models
-class FlightRepositoryImpl @Inject constructor(
-    private val dao: FlightDao,
-    private val mapper: FlightMapper,
-) : FlightRepository {
-
-    override fun getFlights(origin: String): Flow<List<Flight>> =
-        dao.getFlightsByOrigin(origin)
-            .map { entities -> entities.map(mapper::toDomain) }
-            .flowOn(Dispatchers.IO)
-}
+## Reactive Queries with Flow
 
-// ViewModel collects in viewModelScope
-@HiltViewModel
-class FlightListViewModel @Inject constructor(
-    private val repository: FlightRepository,
-) : ViewModel() {
-
-    val flights: StateFlow<List<Flight>> = repository.getFlights("IST")
-        .stateIn(
-            scope = viewModelScope,
-            started = SharingStarted.WhileSubscribed(5_000),
-            initialValue = emptyList(),
-        )
-}
+A DAO method returning `Flow` re-emits whenever its table changes. Map entities
+to domain models in the repository (`.map { ... }.flowOn(Dispatchers.IO)`),
+expose a `StateFlow` from the ViewModel via `stateIn(..., WhileSubscribed(5_000),
+...)`, and collect with `collectAsStateWithLifecycle()` in Compose.
 
-// Compose collects as state
-@Composable
-fun FlightListScreen(viewModel: FlightListViewModel = hiltViewModel()) {
-    val flights by viewModel.flights.collectAsStateWithLifecycle()
-    LazyColumn {
-        items(flights, key = { it.id }) { flight ->
-            FlightCard(flight = flight)
-        }
-    }
-}
-```
+Full repository -> ViewModel -> Compose chain:
+[references/patterns.md#reactive-queries-with-flow](references/patterns.md#reactive-queries-with-flow).
 
 ## TypeConverters
 
-For types Room does not natively support (lists, enums, dates).
-
-```kotlin
-class Converters {
-
-    private val json = Json { ignoreUnknownKeys = true }
-
-    @TypeConverter
-    fun fromStringList(value: List<String>): String =
-        json.encodeToString(value)
-
-    @TypeConverter
-    fun toStringList(value: String): List<String> =
-        json.decodeFromString(value)
-
-    @TypeConverter
-    fun fromInstant(value: Instant?): Long? = value?.toEpochMilliseconds()
+For types Room does not natively support (lists, enums, dates), write a
+`Converters` class with paired `@TypeConverter` functions and register it with
+`@TypeConverters(Converters::class)` on the `@Database` (or a specific entity/DAO).
 
-    @TypeConverter
-    fun toInstant(value: Long?): Instant? = value?.let { Instant.fromEpochMilliseconds(it) }
-
-    @TypeConverter
-    fun fromFlightStatus(value: FlightStatus): String = value.name
-
-    @TypeConverter
-    fun toFlightStatus(value: String): FlightStatus = FlightStatus.valueOf(value)
-}
-```
-
-Register in `@Database`:
-
-```kotlin
-@Database(entities = [...], version = 1)
-@TypeConverters(Converters::class)
-abstract class AppDatabase : RoomDatabase()
-```
+Full converter set (list, `Instant`, enum):
+[references/patterns.md#typeconverters](references/patterns.md#typeconverters).
 
 ## Relations
 
-### @Embedded
-
-Flatten a nested object into the parent table columns:
-
-```kotlin
-data class AddressEntity(
-    val street: String,
-    val city: String,
-    val country: String,
-)
-
-@Entity(tableName = "passengers")
-data class PassengerEntity(
-    @PrimaryKey val id: String,
-    val name: String,
-    @Embedded(prefix = "address_")
-    val address: AddressEntity,
-)
-// Creates columns: id, name, address_street, address_city, address_country
-```
-
-### @Relation (One-to-Many)
-
-```kotlin
-data class BookingWithPassengers(
-    @Embedded val booking: BookingEntity,
-    @Relation(
-        parentColumn = "id",
-        entityColumn = "booking_id",
-    )
-    val passengers: List<BookingPassengerEntity>,
-)
-
-@Dao
-interface BookingDao {
-    @Transaction
-    @Query("SELECT * FROM bookings WHERE id = :bookingId")
-    fun getBookingWithPassengers(bookingId: String): Flow<BookingWithPassengers?>
-}
-```
-
-### Junction Table (Many-to-Many)
-
-```kotlin
-@Entity(
-    tableName = "flight_tags",
-    primaryKeys = ["flight_id", "tag_id"],
-)
-data class FlightTagCrossRef(
-    @ColumnInfo(name = "flight_id") val flightId: String,
-    @ColumnInfo(name = "tag_id") val tagId: String,
-)
-
-data class FlightWithTags(
-    @Embedded val flight: FlightEntity,
-    @Relation(
-        parentColumn = "id",
-        entityColumn = "id",
-        associateBy = Junction(
-            value = FlightTagCrossRef::class,
-            parentColumn = "flight_id",
-            entityColumn = "tag_id",
-        ),
-    )
-    val tags: List<TagEntity>,
-)
-```
+- `@Embedded(prefix = ...)` flattens a nested object into the parent table.
+- `@Relation(parentColumn, entityColumn)` models one-to-many.
+- `associateBy = Junction(...)` models many-to-many through a cross-ref entity.
 
-Always annotate relation queries with `@Transaction` to ensure consistent reads.
+Always annotate relation queries with `@Transaction` for consistent reads.
+Full embedded / one-to-many / junction examples:
+[references/patterns.md#relations](references/patterns.md#relations).
 
 ## Migration Strategies
 
-### Auto Migration (Room 2.4+)
+- Auto migration (`autoMigrations = [AutoMigration(from, to)]`) for additive
+  changes; supply an `AutoMigrationSpec` with `@RenameColumn`/`@DeleteColumn`
+  for renames or deletes.
+- Manual `Migration(from, to)` with raw `execSQL` for data transformation or
+  table merges; register via `.addMigrations(...)`.
+- `.fallbackToDestructiveMigration()` only for development or throwaway data,
+  never in release builds.
 
-For simple schema changes (add column, add table, add index):
+Full auto, manual, and destructive examples:
+[references/patterns.md#migration-strategies](references/patterns.md#migration-strategies).
 
-```kotlin
-@Database(
-    entities = [FlightEntity::class],
-    version = 3,
-    autoMigrations = [
-        AutoMigration(from = 1, to = 2),
-        AutoMigration(from = 2, to = 3, spec = Migration2To3::class),
-    ],
-)
-abstract class AppDatabase : RoomDatabase()
-
-// Spec needed for column/table renames or deletes
-@RenameColumn(tableName = "flights", fromColumnName = "price", toColumnName = "price_amount")
-class Migration2To3 : AutoMigrationSpec
-```
+## Hilt Integration
 
-### Manual Migration
+Provide the database as a `@Singleton` from a `@Module @InstallIn(SingletonComponent::class)`
+object, and provide each DAO from the database instance. Full `DatabaseModule`:
+[references/patterns.md#hilt-integration](references/patterns.md#hilt-integration).
 
-For complex changes (data transformation, merging tables):
+## Encrypted Database (SQLCipher)
 
-```kotlin
-val MIGRATION_3_4 = object : Migration(3, 4) {
-    override fun migrate(db: SupportSQLiteDatabase) {
-        db.execSQL("""
-            CREATE TABLE IF NOT EXISTS bookings_new (
-                id TEXT NOT NULL PRIMARY KEY,
-                flight_id TEXT NOT NULL,
-                status TEXT NOT NULL DEFAULT 'PENDING',
-                created_at INTEGER NOT NULL DEFAULT 0,
-                FOREIGN KEY (flight_id) REFERENCES flights(id) ON DELETE CASCADE
-            )
-        """)
-        db.execSQL("""
-            INSERT INTO bookings_new (id, flight_id, status, created_at)
-            SELECT id, flight_id, status, 0 FROM bookings
-        """)
-        db.execSQL("DROP TABLE bookings")
-        db.execSQL("ALTER TABLE bookings_new RENAME TO bookings")
-    }
-}
+Encrypt the database file by passing a SQLCipher `SupportOpenHelperFactory` to
+`.openHelperFactory(...)` on the builder. This skill owns the encrypted-Room
+wiring; it does not own the passphrase. Derive and store the passphrase through
+the key hierarchy in the `android-security` skill (Keystore-wrapped key), and
+pass the resulting bytes into the factory.
 
-// Register in Hilt module
-Room.databaseBuilder(context, AppDatabase::class.java, "app.db")
-    .addMigrations(MIGRATION_3_4)
-    .build()
-```
+Full builder wiring:
+[references/patterns.md#encrypted-database-sqlcipher](references/patterns.md#encrypted-database-sqlcipher).
 
-### Fallback to Destructive Migration
+## Async Database Provisioning
 
-Only for development or non-critical data:
+When the passphrase (or any setup input) must be derived or fetched before
+`Room.databaseBuilder`, a synchronous `@Provides` cannot await it. Expose the
+database from a suspend, `Mutex`-guarded, double-checked lazy singleton provider
+instead: return the cached instance if present, otherwise build it once inside
+the lock. Hilt provides the provider; repositories fetch DAOs from a suspend
+accessor.
 
-```kotlin
-Room.databaseBuilder(context, AppDatabase::class.java, "app.db")
-    .fallbackToDestructiveMigration()
-    .build()
-```
+Full `DatabaseProvider`:
+[references/patterns.md#async-database-provisioning](references/patterns.md#async-database-provisioning).
 
-## Hilt Integration
+## Runtime Hygiene
 
-```kotlin
-@Module
-@InstallIn(SingletonComponent::class)
-object DatabaseModule {
-
-    @Provides
-    @Singleton
-    fun provideDatabase(@ApplicationContext context: Context): AppDatabase =
-        Room.databaseBuilder(
-            context,
-            AppDatabase::class.java,
-            "app.db",
-        )
-        .addMigrations(MIGRATION_3_4)
-        .build()
-
-    @Provides
-    fun provideFlightDao(database: AppDatabase): FlightDao =
-        database.flightDao()
-
-    @Provides
-    fun provideBookingDao(database: AppDatabase): BookingDao =
-        database.bookingDao()
-}
-```
+- Cap WAL file growth on a write-heavy database with an `onOpen` callback issuing
+  `PRAGMA wal_autocheckpoint`.
+- Do multi-step read-then-write logic (dedupe, insert, trim-to-cap) atomically in
+  a `@Transaction` DAO default method, not across separate DAO calls.
+- `exportSchema = false` is acceptable only for a cache or destructive-fallback
+  database whose file is disposable. A migration-tested production database keeps
+  `exportSchema = true` and commits its schema JSON, which `MigrationTestHelper`
+  validates against.
 
-## Testing with In-Memory Database
+Full callback and transactional DAO:
+[references/patterns.md#runtime-hygiene](references/patterns.md#runtime-hygiene).
 
-```kotlin
-class FlightDaoTest {
-
-    private lateinit var database: AppDatabase
-    private lateinit var dao: FlightDao
-
-    @Before
-    fun setup() {
-        database = Room.inMemoryDatabaseBuilder(
-            ApplicationProvider.getApplicationContext(),
-            AppDatabase::class.java,
-        )
-        .allowMainThreadQueries() // OK for tests only
-        .build()
-
-        dao = database.flightDao()
-    }
-
-    @After
-    fun tearDown() {
-        database.close()
-    }
-
-    @Test
-    fun insertAndQuery_returnsCorrectFlight() = runTest {
-        val flight = FlightEntity(
-            id = "TK1",
-            originCode = "IST",
-            originName = "Istanbul",
-            destinationCode = "JFK",
-            destinationName = "New York",
-            departureTime = "2025-01-15T10:00:00Z",
-            arrivalTime = "2025-01-15T18:00:00Z",
-            priceAmount = 799.0,
-            priceCurrency = "USD",
-            status = "SCHEDULED",
-        )
-
-        dao.insertFlight(flight)
-
-        val result = dao.getFlightByIdOnce("TK1")
-        assertThat(result).isNotNull()
-        assertThat(result?.originCode).isEqualTo("IST")
-    }
-
-    @Test
-    fun flowQuery_emitsUpdates() = runTest {
-        dao.getFlights("IST", "JFK").test {
-            assertThat(awaitItem()).isEmpty()
-
-            dao.insertFlight(testFlight)
-
-            val updated = awaitItem()
-            assertThat(updated).hasSize(1)
-
-            cancelAndIgnoreRemainingEvents()
-        }
-    }
-
-    @Test
-    fun upsert_updatesExistingFlight() = runTest {
-        dao.insertFlight(testFlight)
-        val updated = testFlight.copy(status = "DELAYED")
-        dao.upsertFlights(listOf(updated))
-
-        val result = dao.getFlightByIdOnce(testFlight.id)
-        assertThat(result?.status).isEqualTo("DELAYED")
-    }
-}
-```
+## Testing with In-Memory Database
 
-### Testing Migrations
+Build a `Room.inMemoryDatabaseBuilder(...)` in `@Before`, close it in `@After`,
+and run DAO tests with `runTest`. Use Turbine's `.test { awaitItem() }` for
+`Flow` assertions. Test migrations with `MigrationTestHelper`
+(`createDatabase` at the old version, then `runMigrationsAndValidate`).
 
-```kotlin
-@RunWith(AndroidJUnit4::class)
-class MigrationTest {
-
-    @get:Rule
-    val helper = MigrationTestHelper(
-        InstrumentationRegistry.getInstrumentation(),
-        AppDatabase::class.java,
-    )
-
-    @Test
-    fun migrate3To4() {
-        // Create database at version 3
-        helper.createDatabase("test-db", 3).apply {
-            execSQL("INSERT INTO bookings (id, flight_id, status) VALUES ('B1', 'F1', 'CONFIRMED')")
-            close()
-        }
-
-        // Run migration and validate
-        val db = helper.runMigrationsAndValidate("test-db", 4, true, MIGRATION_3_4)
-        val cursor = db.query("SELECT * FROM bookings WHERE id = 'B1'")
-        assertThat(cursor.moveToFirst()).isTrue()
-        assertThat(cursor.getColumnIndex("created_at")).isAtLeast(0)
-    }
-}
-```
+Full DAO tests and migration test:
+[references/patterns.md#testing-with-in-memory-database](references/patterns.md#testing-with-in-memory-database).
 
 ## Do's and Don'ts
 
@@ -527,6 +179,10 @@ class MigrationTest {
 - Use in-memory databases for unit tests
 - Test migrations with `MigrationTestHelper`
 - Use `stateIn` with `WhileSubscribed(5000)` in ViewModels for Flow collection
+- Encrypt sensitive databases with a SQLCipher `SupportOpenHelperFactory`
+- Build a database needing async setup from a suspend, `Mutex`-guarded provider
+- Cap WAL growth with an `onOpen` `PRAGMA wal_autocheckpoint`
+- Keep multi-step read-then-write logic inside a `@Transaction` default method
 
 ### Don'ts
 - Do not perform Room operations on the main thread (except in tests with `allowMainThreadQueries`)
@@ -561,4 +217,9 @@ class MigrationTest {
 - [ ] Migrations tested with `MigrationTestHelper`
 - [ ] No `fallbackToDestructiveMigration` in release builds
 - [ ] DAOs provided via Hilt as singletons (database) / transient (DAOs)
+- [ ] Sensitive databases encrypted via a SQLCipher `SupportOpenHelperFactory`
+- [ ] Passphrase sourced from the `android-security` key hierarchy, not reproduced
+- [ ] Async-setup databases built from a suspend, `Mutex`-guarded provider
+- [ ] `onOpen` `PRAGMA wal_autocheckpoint` on write-heavy databases
+- [ ] Multi-step read-then-write logic wrapped in a `@Transaction` default method
 - [ ] In-memory database used in unit tests