@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.0

package/pipeline/skills/shared/external/android-build-quality-gates/references/patterns.md

@@ -0,0 +1,432 @@
+# Android Build Quality Gates - Patterns
+
+Full, copy-ready code for the gates summarized in
+[../SKILL.md](../SKILL.md). Each section mirrors a heading there. Adapt names to
+the project's module conventions; nothing here hardcodes a product.
+
+## Layer-dependency gate
+
+Convention plugin `build-logic/convention/src/main/kotlin/quality/LayerGate.kt`.
+It derives a module's layer from its path, resolves the allowed set for that
+layer, and fails on any project dependency outside it.
+
+```kotlin
+package quality
+
+import org.gradle.api.GradleException
+import org.gradle.api.Project
+import org.gradle.api.artifacts.ProjectDependency
+import org.gradle.kotlin.dsl.withType
+
+enum class Layer {
+    APP, FEATURE, DOMAIN, DATA, CORE, UNKNOWN;
+
+    fun allows(depPath: String): Boolean {
+        val depLayer = layerOf(depPath)
+        return when (this) {
+            APP -> true
+            FEATURE -> depLayer in setOf(DOMAIN, CORE)
+            DOMAIN -> depLayer in setOf(DOMAIN, CORE)
+            DATA -> depLayer in setOf(DOMAIN, CORE, DATA)
+            CORE -> depLayer in setOf(CORE)
+            UNKNOWN -> true
+        }
+    }
+
+    companion object {
+        fun layerOf(path: String): Layer {
+            val name = path.substringAfterLast(":")
+            return when {
+                name.startsWith("app") -> APP
+                name.startsWith("feature") -> FEATURE
+                name.startsWith("domain") -> DOMAIN
+                name.startsWith("data") -> DATA
+                name.startsWith("core") -> CORE
+                else -> UNKNOWN
+            }
+        }
+    }
+}
+
+fun Project.moduleLayer(): Layer = Layer.layerOf(path)
+
+fun Project.registerLayerGate() {
+    val layer = moduleLayer()
+    val projectDeps = configurations
+        .matching { it.name in setOf("implementation", "api") }
+        .flatMap { conf -> conf.dependencies.withType<ProjectDependency>().map { it.path } }
+        .distinct()
+
+    val checkLayerDependencies = tasks.register("checkLayerDependencies") {
+        group = "verification"
+        description = "Fails when this module depends on a forbidden layer"
+        doLast {
+            val forbidden = projectDeps.filterNot { layer.allows(it) }
+            if (forbidden.isNotEmpty()) {
+                throw GradleException(
+                    buildString {
+                        appendLine("$path ($layer) declares forbidden dependencies:")
+                        forbidden.forEach { appendLine("  - $it (${Layer.layerOf(it)})") }
+                        append("Allowed targets for $layer are enforced in Layer.allows().")
+                    }
+                )
+            }
+        }
+    }
+    tasks.named("check").configure { dependsOn(checkLayerDependencies) }
+}
+```
+
+`projectDeps` is materialized into a `List<String>` at configuration time, so
+`doLast` never touches the live `configurations` container and the task is
+configuration-cache safe. Apply from a module's `build.gradle.kts` with
+`registerLayerGate()` after the plugin block, or fold the call into a broader
+`AndroidLibraryConventionPlugin`.
+
+For a temporary accepted exception, prefer a narrow per-edge allowlist over
+widening `allows`:
+
+```kotlin
+private val acceptedEdges = setOf(
+    ":feature-legacy" to ":data-legacy", // TRACKING-1234, remove after migration
+)
+
+fun Layer.allowsWithExceptions(fromPath: String, depPath: String): Boolean =
+    allows(depPath) || (fromPath to depPath) in acceptedEdges
+```
+
+## Coverage floor with Kover
+
+Per-module: apply the plugin and exclude generated code.
+
+```kotlin
+plugins {
+    id("org.jetbrains.kotlinx.kover")
+}
+
+kover {
+    reports {
+        filters {
+            excludes {
+                classes(
+                    "*_Factory",
+                    "*_Factory\$*",
+                    "*.BuildConfig",
+                    "*Args",
+                    "*Directions",
+                    "hilt_aggregated_deps.*",
+                    "*_HiltModules*",
+                    "dagger.hilt.*",
+                )
+                annotatedBy("androidx.compose.runtime.Composable")
+            }
+        }
+    }
+}
+```
+
+Aggregation module `coverage/build.gradle.kts` depends on every measured module
+and owns the single verify rule:
+
+```kotlin
+plugins {
+    id("org.jetbrains.kotlinx.kover")
+}
+
+dependencies {
+    kover(project(":feature-a"))
+    kover(project(":feature-b"))
+    kover(project(":domain"))
+    kover(project(":data"))
+}
+
+kover {
+    reports {
+        total {
+            verify {
+                rule("Aggregate line coverage floor") {
+                    bound {
+                        minValue = 60 // seed at measured value, ratchet up
+                        coverageUnits = kotlinx.kover.gradle.plugin.dsl.CoverageUnit.LINE
+                        aggregationForGroup =
+                            kotlinx.kover.gradle.plugin.dsl.AggregationType.COVERED_PERCENTAGE
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+Gate behind a property so local builds skip instrumented coverage:
+
+```kotlin
+tasks.named("check").configure {
+    if (providers.gradleProperty("enableCoverageVerification").isPresent) {
+        dependsOn("koverVerify")
+    }
+}
+```
+
+CI: `./gradlew :coverage:check -PenableCoverageVerification`.
+
+## Compose-stability gate
+
+Point the compiler at a metrics dir (per-module, in the Android/compose
+convention plugin):
+
+```kotlin
+composeCompiler {
+    val metricsDir = layout.buildDirectory.dir("compose-metrics")
+    metricsDestination.set(metricsDir)
+    reportsDestination.set(metricsDir)
+}
+```
+
+The check task parses `*-composables.txt`. A composable line the compiler emits
+looks like `restartable skippable fun HomeScreen(...)` or, when it cannot skip,
+`restartable fun HomeScreen(...)` (no `skippable`). The gate fails on the second
+shape unless the composable is in the ignore-list.
+
+```kotlin
+package quality
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.GradleException
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.provider.ListProperty
+import org.gradle.api.tasks.InputDirectory
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.Optional
+import org.gradle.api.tasks.TaskAction
+
+abstract class ComposeStabilityCheck : DefaultTask() {
+
+    @get:InputDirectory
+    abstract val reportDir: DirectoryProperty
+
+    @get:InputFile
+    @get:Optional
+    abstract val ignoreFile: RegularFileProperty
+
+    private val restartableNotSkippable =
+        Regex("""^restartable (?!skippable)fun (\w+)""")
+
+    @TaskAction
+    fun check() {
+        val dir = reportDir.get().asFile
+        if (!dir.exists()) return
+
+        val ignored: Set<String> = ignoreFile.orNull?.asFile
+            ?.takeIf { it.exists() }
+            ?.readLines()
+            ?.map { it.substringBefore('#').trim() }
+            ?.filter { it.isNotEmpty() }
+            ?.toSet()
+            ?: emptySet()
+
+        val offenders = dir.walkTopDown()
+            .filter { it.name.endsWith("-composables.txt") }
+            .flatMap { file -> file.readLines().asSequence() }
+            .mapNotNull { line -> restartableNotSkippable.find(line.trim())?.groupValues?.get(1) }
+            .filterNot { it in ignored }
+            .distinct()
+            .toList()
+
+        if (offenders.isNotEmpty()) {
+            throw GradleException(
+                buildString {
+                    appendLine("Unskippable composables (restartable but not skippable):")
+                    offenders.forEach { appendLine("  - $it") }
+                    appendLine("Fix the unstable parameter, or add the name to")
+                    append(ignoreFile.orNull?.asFile?.path ?: "the stability ignore-list")
+                }
+            )
+        }
+    }
+}
+```
+
+Register it and finalize each Kotlin compile so the report is fresh:
+
+```kotlin
+val checkComposeStability = tasks.register("checkComposeStability", ComposeStabilityCheck::class.java) {
+    group = "verification"
+    reportDir.set(layout.buildDirectory.dir("compose-metrics"))
+    ignoreFile.set(layout.projectDirectory.file("compose-stability-ignore.txt"))
+}
+
+tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile::class.java).configureEach {
+    finalizedBy(checkComposeStability)
+}
+tasks.named("check").configure { dependsOn(checkComposeStability) }
+```
+
+`compose-stability-ignore.txt` (per module), seeded with today's offenders:
+
+```
+# Accepted exceptions. Each line: composable name. Shrink over time; additions reviewed.
+LegacyChartView   # takes third-party unstable ChartModel, TRACKING-2201
+```
+
+## Lint on diff
+
+Pre-commit hook `.git/hooks/pre-commit` (or a managed hook via a Gradle plugin):
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+CHANGED=$(git diff --cached --name-only --diff-filter=d -- '*.kt' '*.kts')
+if [ -z "$CHANGED" ]; then
+  exit 0
+fi
+
+./gradlew detektDiff -PdetektInput="$CHANGED" --quiet
+```
+
+`detektDiff` task, in the quality convention plugin, points detekt at only the
+changed files while keeping the shared config and baseline:
+
+```kotlin
+plugins {
+    id("io.gitlab.arturbosch.detekt")
+}
+
+detekt {
+    buildUponDefaultConfig = true
+    config.setFrom(rootProject.files("config/detekt/detekt.yml"))
+    baseline = rootProject.file("config/detekt/baseline.xml")
+}
+
+tasks.register("detektDiff", io.gitlab.arturbosch.detekt.Detekt::class.java) {
+    group = "verification"
+    description = "Runs detekt over only the files passed in -PdetektInput"
+    val input = providers.gradleProperty("detektInput").orElse("")
+    setSource(files(input.get().split(Regex("\\s+")).filter { it.isNotBlank() }))
+    config.setFrom(rootProject.files("config/detekt/detekt.yml"))
+    baseline.set(rootProject.file("config/detekt/baseline.xml"))
+    buildUponDefaultConfig = true
+    include("**/*.kt", "**/*.kts")
+}
+```
+
+CI runs the full task with the same config and baseline:
+
+```yaml
+- name: Detekt (full)
+  run: ./gradlew detekt --continue
+```
+
+Regenerate the baseline deliberately (`./gradlew detektBaseline`) and review the
+diff; a baseline change that buries a new finding is a review smell.
+
+## Screenshot validation task
+
+Author the tests per `compose-testing`. Here, register the record/verify pair
+and the umbrella task. Example with Roborazzi:
+
+```kotlin
+tasks.register("recordScreenshots") {
+    group = "verification"
+    description = "Regenerates golden images; run deliberately, review the diff"
+    dependsOn(tasks.matching { it.name == "recordRoborazziDebug" })
+}
+
+tasks.register("verifyScreenshots") {
+    group = "verification"
+    description = "Compares against goldens and fails on mismatch or missing golden"
+    dependsOn(tasks.matching { it.name == "verifyRoborazziDebug" })
+}
+
+tasks.named("check").configure { dependsOn("verifyScreenshots") }
+```
+
+Configure the tool so a missing golden fails rather than records:
+
+```kotlin
+roborazzi {
+    outputDir.set(layout.projectDirectory.dir("src/test/screenshots"))
+    verify {
+        // do NOT enable a record-on-missing fallback in the verify task
+    }
+}
+```
+
+CI uploads diff images on failure so the reviewer sees the pixel change:
+
+```yaml
+- name: Verify screenshots
+  run: ./gradlew verifyScreenshots
+- name: Upload diffs
+  if: failure()
+  uses: actions/upload-artifact@v4
+  with:
+    name: screenshot-diffs
+    path: '**/build/outputs/roborazzi/*_compare.png'
+```
+
+## Wiring gates into check
+
+Assemble every gate in one quality convention plugin and expose a single
+aggregate task. This is what a module gets by applying the plugin.
+
+```kotlin
+package quality
+
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+
+class QualityGatesConventionPlugin : Plugin<Project> {
+    override fun apply(target: Project) = with(target) {
+        registerLayerGate()
+
+        val checkComposeStability = tasks.register(
+            "checkComposeStability", ComposeStabilityCheck::class.java
+        ) {
+            group = "verification"
+            reportDir.set(layout.buildDirectory.dir("compose-metrics"))
+            ignoreFile.set(layout.projectDirectory.file("compose-stability-ignore.txt"))
+        }
+        tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile::class.java)
+            .configureEach { finalizedBy(checkComposeStability) }
+
+        val qualityGates = tasks.register("qualityGates") {
+            group = "verification"
+            description = "Runs all fast, always-on build quality gates"
+            dependsOn(
+                "checkLayerDependencies",
+                "checkComposeStability",
+            )
+            if (tasks.findByName("verifyScreenshots") != null) {
+                dependsOn("verifyScreenshots")
+            }
+        }
+
+        tasks.named("check").configure {
+            dependsOn(qualityGates)
+            if (providers.gradleProperty("enableCoverageVerification").isPresent) {
+                dependsOn("koverVerify")
+            }
+        }
+    }
+}
+```
+
+Register the plugin in `build-logic/convention/build.gradle.kts`:
+
+```kotlin
+gradlePlugin {
+    plugins {
+        register("qualityGates") {
+            id = "convention.quality.gates"
+            implementationClass = "quality.QualityGatesConventionPlugin"
+        }
+    }
+}
+```
+
+Apply from any module: `plugins { id("convention.quality.gates") }`. A single
+`./gradlew check` then runs the fast gates locally; CI adds `-P` flags for the
+expensive ones.

package/pipeline/skills/shared/external/android-datastore/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: android-datastore
+description: "Typed Jetpack DataStore as the modern SharedPreferences replacement: Preferences and typed stores, serializer-layer encryption, and migration. Use when persisting settings, session or tokens, encrypting key-value state, or migrating off EncryptedSharedPreferences."
+risk: safe
+source: multi-agent-pipeline
+date_added: "2026-09-21"
+---
+
+# Android DataStore
+
+Jetpack DataStore is the current replacement for `SharedPreferences`: an
+async, transactional, coroutine- and Flow-based key-value or typed store that
+never blocks the UI thread and surfaces read errors instead of swallowing them.
+Targets DataStore 1.1+ with Kotlin coroutines.
+
+Full copy-ready code for every section lives in
+[`references/patterns.md`](references/patterns.md), under headings that mirror
+these sections. Read a section here for the decision, load the matching
+reference section when writing the implementation.
+
+## Contents
+
+- [Choosing a Store](#choosing-a-store)
+- [Preferences DataStore](#preferences-datastore)
+- [Typed DataStore with a Serializer](#typed-datastore-with-a-serializer)
+- [Encrypted Typed DataStore](#encrypted-typed-datastore)
+- [Migrating from SharedPreferences](#migrating-from-sharedpreferences)
+- [Versioned Data Migrations](#versioned-data-migrations)
+- [Reading and Writing as Flow](#reading-and-writing-as-flow)
+- [Testing](#testing)
+- [Do's and Don'ts](#dos-and-donts)
+- [Troubleshooting](#troubleshooting)
+- [Review Checklist](#review-checklist)
+
+## Choosing a Store
+
+Two flavors share one engine. Pick by whether the shape of the data is fixed.
+
+| Need | Store | Why |
+|------|-------|-----|
+| A handful of loose keys, types known only at the call site | Preferences DataStore | No schema, `Preferences.Key<T>` accessors, quickest to adopt |
+| A fixed model with named fields, validation, defaults | Typed DataStore | One `Serializer`, compile-time-safe reads, atomic whole-object writes |
+| Small sensitive state (tokens, flags tied to a session) | Typed DataStore + encrypting `Serializer` | Encryption sits in the serialization layer, transparent to callers |
+| Large sensitive or relational data | Not DataStore | Use `room-database` (encrypted relational storage) |
+| Cryptographic keys themselves | Not DataStore | Use `android-security` (Keystore key hierarchy) |
+
+Preferences DataStore trades the schema for flexibility: no type safety, no
+defaults, no validation. Reach for the typed flavor as soon as the data has a
+stable shape. "Proto DataStore" is the same typed mechanism using a protobuf
+`Serializer`; nothing here requires protobuf specifically, any serialization
+(a hand-written `Serializer`, kotlinx-serialization JSON, protobuf) works
+behind the `Serializer<T>` interface.
+
+Declare each store once per process as a top-level property so a single
+instance owns the file; two instances over one file corrupt it.
+
+## Preferences DataStore
+
+Create the store with the `preferencesDataStore` delegate, define typed keys
+with `stringPreferencesKey`, `intPreferencesKey`, `booleanPreferencesKey`, and
+read `data` as a `Flow<Preferences>`, mapping each key with a default. Write
+inside `edit { }`, a transactional block.
+
+See [references/patterns.md#preferences-datastore](references/patterns.md#preferences-datastore)
+for the store declaration, a typed read Flow, and a write.
+
+## Typed DataStore with a Serializer
+
+A typed store needs a `Serializer<T>` supplying a `defaultValue` and
+`readFrom` / `writeTo` over streams. Model the data as an immutable type
+(a `data class` or a protobuf message), then create the store with the
+`dataStore` delegate passing `fileName` and `serializer`.
+
+`readFrom` failure must throw `CorruptionException`, which the optional
+`corruptionHandler` (a `ReplaceFileCorruptionHandler`) turns into a recovery
+value instead of crashing the app.
+
+See [references/patterns.md#typed-datastore-with-a-serializer](references/patterns.md#typed-datastore-with-a-serializer)
+for a `data class` model, a JSON `Serializer`, and the store declaration with a
+corruption handler.
+
+## Encrypted Typed DataStore
+
+Encrypt at the `Serializer` layer: the store persists ciphertext, callers see
+the plain model, and encryption is invisible to the rest of the app. A generic
+`createEncryptedDataStore(name, serializer)` factory wraps any inner
+`Serializer<T>` in an encrypting one so a single implementation serves every
+model.
+
+Contract of the encrypting `Serializer`:
+
+- **Encrypt per write.** Serialize with the inner serializer, encrypt the
+  bytes with an AES/GCM key from the Keystore.
+- **Prepend the IV to the ciphertext.** GCM needs a fresh random IV per
+  encryption; write `IV || ciphertext` so `readFrom` can split the IV back off.
+  Never reuse an IV with the same key.
+- **Fail safe on any read error.** A decryption failure, a truncated file, a
+  key rotation, a format change: `readFrom` returns the inner serializer's
+  `defaultValue` rather than throwing. Corrupt or unreadable encrypted state
+  degrades to "empty", it never crashes and never leaks a partial plaintext.
+- **Debug-only plaintext escape hatch (optional).** Guarded by
+  `BuildConfig.DEBUG`, write plaintext instead of ciphertext so the file is
+  inspectable on a developer build. Release builds always encrypt; the branch
+  is compiled out by R8.
+
+The AES/GCM Keystore key belongs to `android-security` (key hierarchy,
+envelope encryption, `KeyPermanentlyInvalidatedException` handling); this
+factory only consumes a `Cipher` from it. `EncryptedSharedPreferences` and the
+`androidx.security-crypto` `MasterKey` it depends on are deprecated; a typed
+DataStore with an encrypting `Serializer` is the current-best-practice
+replacement and keeps encryption and typing in one place.
+
+See [references/patterns.md#encrypted-typed-datastore](references/patterns.md#encrypted-typed-datastore)
+for the full `EncryptingSerializer<T>` (IV split/prepend, fail-safe read,
+debug plaintext branch) and the `createEncryptedDataStore` factory.
+
+## Migrating from SharedPreferences
+
+Pass a `SharedPreferencesMigration` in the store's `produceMigrations`. On
+first read after upgrade, DataStore copies the named keys out of the legacy
+`SharedPreferences` into the store, then deletes the migrated keys so the copy
+runs exactly once. List the keys explicitly to migrate a subset; omit the set
+to migrate all keys.
+
+For a typed store, the migration maps the flat `SharedPreferences` values onto
+the model's fields inside the migration lambda.
+
+See [references/patterns.md#migrating-from-sharedpreferences](references/patterns.md#migrating-from-sharedpreferences)
+for a Preferences-store migration and a typed-store migration.
+
+## Versioned Data Migrations
+
+Carry a `version` (or `schemaVersion`) field in the typed model and register a
+`DataMigration<T>` whose `shouldMigrate` compares the stored version, whose
+`migrate` returns the upgraded value, and whose `cleanUp` releases any
+transient resources. Chain one migration per version step so an old install
+walks forward one version at a time. Migrations run in order before the first
+`data` emission.
+
+See [references/patterns.md#versioned-data-migrations](references/patterns.md#versioned-data-migrations)
+for a versioned model and a stepwise `DataMigration`.
+
+## Reading and Writing as Flow
+
+`data` is a cold `Flow<T>` that re-emits the whole value on every write.
+
+- **Observe** by collecting `data`; map to the field you need and add
+  `distinctUntilChanged()` to drop no-op re-emissions.
+- **Read once** with `data.first()` inside a coroutine.
+- **Handle IO errors in the stream**: catch `IOException` from `data` with
+  `.catch { }` and emit the default; let other exceptions propagate.
+- **Write** with `updateData { current -> ... }` (typed) or `edit { }`
+  (Preferences). Both suspend, run on the DataStore dispatcher, and are atomic:
+  the transform receives the current value and returns the next, so
+  read-modify-write races cannot interleave. Never mutate and re-store from a
+  separately read snapshot; always transform inside the block.
+
+Do the work in `viewModelScope` / an injected scope with structured
+concurrency; DataStore confines its own IO, so no manual `Dispatchers.IO`
+wrapping is needed around `updateData` or `edit`.
+
+See [references/patterns.md#reading-and-writing-as-flow](references/patterns.md#reading-and-writing-as-flow)
+for an observed Flow with error handling, a one-shot read, and an atomic update.
+
+## Testing
+
+Point the store at a `TemporaryFolder` file and drive it with a `TestScope`.
+
+- Build the store with `DataStoreFactory.create(...)` (or the typed factory)
+  and a `scope` of `TestScope(...) + Job()`, backed by a file under a JUnit
+  `TemporaryFolder` so each test is isolated and self-cleaning.
+- Drive time with `runTest`; assert on `data.first()` after an `updateData`.
+- For the encrypting serializer, inject a fake/in-memory `Cipher` provider so
+  the test does not touch the real Keystore, and assert a corrupt file yields
+  the default (fail-safe), not an exception.
+- No `Thread.sleep`; `runTest` advances the virtual clock. No shared global
+  store between tests; one file per test.
+
+See [references/patterns.md#testing](references/patterns.md#testing)
+for a `TemporaryFolder`-backed store, a `runTest` round-trip, and a fail-safe
+corruption test.
+
+## Do's and Don'ts
+
+### Do's
+- Declare one DataStore instance per file, as a top-level property
+- Prefer a typed DataStore once the data has a stable shape
+- Encrypt in the `Serializer` layer so callers stay plaintext-only
+- Prepend a fresh random IV to every GCM ciphertext
+- Return the default value on any encrypted-read failure (fail safe)
+- Read/write through `data`, `updateData`, and `edit` only
+- Transform inside `updateData { }` / `edit { }`, never mutate a snapshot
+- Add `distinctUntilChanged()` when observing a single field
+- Migrate legacy keys with `SharedPreferencesMigration`
+- Version the typed model and migrate stepwise
+- Back tests with a `TemporaryFolder` file and a `TestScope`
+
+### Don'ts
+- Do not create two DataStore instances over one file
+- Do not use `runBlocking` to read on the main thread
+- Do not reuse an IV with the same AES/GCM key
+- Do not throw from an encrypted `readFrom`; degrade to the default
+- Do not write plaintext in release builds (gate the branch on `BuildConfig.DEBUG`)
+- Do not store cryptographic keys in DataStore (Keystore owns those)
+- Do not put large or relational data in DataStore (use Room)
+- Do not wrap `updateData`/`edit` in `Dispatchers.IO`; DataStore confines IO
+- Do not read a snapshot, mutate, and store it back (race)
+- Do not use `EncryptedSharedPreferences`; it is deprecated
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `IllegalStateException: multiple DataStores active for the same file` | Two instances over one file | Keep a single top-level instance |
+| `CorruptionException` on first read | Unreadable file / schema change | Add a `corruptionHandler` (`ReplaceFileCorruptionHandler`) or fail safe to default |
+| Decrypt fails after re-enroll / OS update | Keystore key invalidated | Catch in `readFrom`, return default; recreate the key (see android-security) |
+| `data` never emits | Collected off a cancelled scope, or a migration threw | Collect in a live scope; check migration `shouldMigrate`/`migrate` |
+| SharedPreferences values not appearing | Keys not listed, or already migrated once | List the keys; migration copies each key only once |
+| Stale value after write | Read from a cached snapshot, not `data` | Always observe `data`; write via `updateData` |
+| `GeneralSecurityException` / `AEADBadTagException` on read | IV/ciphertext split wrong or tampered file | Verify `IV || ciphertext` framing; on failure return default |
+| Flaky test, wrong value | Shared store or real dispatcher | One `TemporaryFolder` file per test; `TestScope` + `runTest` |
+
+## Review Checklist
+
+- [ ] One DataStore instance per file, declared top-level
+- [ ] Typed DataStore used where the data shape is stable
+- [ ] Encryption lives in the `Serializer`, callers see plaintext
+- [ ] Fresh random IV per write, prepended to the ciphertext
+- [ ] Encrypted `readFrom` fails safe to the default value, never throws
+- [ ] Any debug plaintext path is gated on `BuildConfig.DEBUG`
+- [ ] Cryptographic keys come from the Keystore, not DataStore (android-security)
+- [ ] Large / relational data uses Room, not DataStore (room-database)
+- [ ] `SharedPreferencesMigration` covers the legacy keys
+- [ ] Typed model is versioned with stepwise `DataMigration`s
+- [ ] Reads/writes go through `data`, `updateData`, `edit`; no cached snapshots
+- [ ] Tests use a `TemporaryFolder` file and a `TestScope`, no `sleep`