Local message cache: instant start + offline reading (SQLDelight)

- Cache.sq / ChatDb: lanes, channels and last_lane persisted as JSON
  snapshots; sanitize on restore (Pending->Failed, streaming->false);
  ephemeral items (tool, system) skipped
- Platform drivers via expect/actual: AndroidSqliteDriver (app db dir)
  / JdbcSqliteDriver (~/.iris/iris_cache.db)
- IrisController: restore before connect, debounced (750ms) snapshot
  persistence, synchronous flush on dispose, clearAll on forget
- History robustness: historyLoaded marked only when the response is
  processed (lost request/response retried on reconnect); events
  collector wrapped in try/catch; onHelloAck fast path so the history
  request fires on the WS thread instead of the starved state
  collector; frame-decode and history-load logging
- Protocol: HistoryMessage.media nullable (defensive vs older
  gateways that sent "media": null)
- Tests: ChatDbTest (jvmTest, JDBC in-memory), ChatStoreCacheTest,
  HistoryPayloadTest, HistoryWireTest (real captured 92KB response)
- docs/10: §10.7 implemented schema, new §10.9 cache behavior

app/shared/build.gradle.kts

@@ -6,6 +6,8 @@ plugins {
     id("com.android.kotlin.multiplatform.library")
     id("org.jetbrains.compose")
     id("org.jetbrains.kotlin.plugin.compose")
+    // Local cache DB (docs/16: "Local DB (KMP) — SQLDelight").
+    id("app.cash.sqldelight")
 }
 
 val composeVersion = "1.11.1"
@@ -25,6 +27,8 @@ val kcefVersion = "2025.03.23"
 // release). Provides GFM tables, bold/italic/underscore, and the -code module
 // for language-aware syntax highlighting (Highlights).
 val markdownVersion = "0.44.0"
+// Local cache DB (messages/channels/meta; docs/10 §10.7, docs/16).
+val sqldelightVersion = "2.3.2"
 
 kotlin {
     android {
@@ -51,6 +55,11 @@ kotlin {
         val jvmMain by creating { dependsOn(commonMain.get()) }
         val androidMain by getting { dependsOn(jvmMain) }
         val desktopMain by getting { dependsOn(jvmMain) }
+        // Host tests shared by the android (withHostTest) and desktop targets
+        // (e.g. the SQLDelight cache DB tests, which need the JDBC driver).
+        val jvmTest by creating { dependsOn(commonTest.get()) }
+        val androidHostTest by getting { dependsOn(jvmTest) }
+        val desktopTest by getting { dependsOn(jvmTest) }
 
         commonMain.dependencies {
             implementation("org.jetbrains.compose.runtime:runtime:$composeVersion")
@@ -74,15 +83,24 @@ kotlin {
             // M9: HTML artifact previews — WebView composable (platform WebView
             // on Android, KCEF/JCEF on desktop).
             implementation("io.github.kevinnzou:compose-webview-multiplatform:$webviewVersion")
+            // Local cache DB runtime (generated code from commonMain/sqldelight).
+            implementation("app.cash.sqldelight:runtime:$sqldelightVersion")
         }
         commonTest.dependencies {
             implementation(kotlin("test"))
         }
+        jvmTest.dependencies {
+            implementation(kotlin("test"))
+            // JDBC SQLite driver: in-memory DB for the cache tests.
+            implementation("app.cash.sqldelight:sqlite-driver:$sqldelightVersion")
+        }
         // M9: KCEF (JCEF/Chromium) for desktop HTML artifact previews. The
         // webview library exposes it transitively, but we reference KCEF
         // directly (init + progress) so declare it explicitly.
         desktopMain.dependencies {
             implementation("dev.datlag:kcef:$kcefVersion")
+            // Local cache DB: JDBC SQLite driver (file in ~/.iris).
+            implementation("app.cash.sqldelight:sqlite-driver:$sqldelightVersion")
         }
         // M4: ExoPlayer (Media3) for inline audio/video playback (Android only).
         androidMain.dependencies {
@@ -97,6 +115,16 @@ kotlin {
             // the ntfy listener is the fallback). The google-services plugin is
             // applied conditionally in the app module.
             implementation("com.google.firebase:firebase-messaging:25.1.2")
+            // Local cache DB: Android SQLite driver (app database dir).
+            implementation("app.cash.sqldelight:android-driver:$sqldelightVersion")
+        }
+    }
+}
+
+sqldelight {
+    databases {
+        create("IrisDatabase") {
+            packageName.set("iris.db")
         }
     }
 }