fix: explain dynamic app contract fallbacks without exception text

PLATFORMS.md

@@ -27,17 +27,19 @@ The app is built from four layers. Only the last one is platform-specific.
 
 ## Modules and source sets
 
-This section describes where code lives today. The Gradle build has three
-modules (`settings.gradle.kts`); the Rust crate is built separately.
+**Last reviewed: 2026-10-17.** This section describes where code lives; the
+code may have changed since, and the default branch is the source of truth.
+The Gradle build has three modules (`settings.gradle.kts`); the Rust crate is
+built separately.
 
 | Location | What it owns |
 | --- | --- |
 | `ui/src/commonMain` | Platform-neutral models, policies, repositories, the dynamic descriptor compiler (`nativeui/model`), the native renderer (`nativeui/runtime`), and Compose screens. The `NextcloudPlatformServices` interface is declared here. |
-| `ui/src/jvmMain` | Code that is identical on Android and desktop: OkHttp request helpers, the authenticated app-read session, detached downloads, resumable uploads, text-draft encryption, and support diagnostics. |
+| `ui/src/jvmMain` | Code that is identical on Android and desktop: OkHttp request helpers, the authenticated app-read session, the App Store contract acquisition boundary, detached downloads, resumable uploads, text-draft encryption, and support diagnostics. |
 | `ui/src/androidMain` | Android `actual` implementations used by the shared UI, such as audio and video playback services, image decoding, back handling, the embedded Office editor, and server certificate trust. |
 | `ui/src/desktopMain` | The complete desktop platform: `DesktopNextcloudServices`, secret stores, the desktop sync engine and its SQLite stores, Linux FUSE virtual files, Windows Cloud Files, tray integration, in-app video playback through vlcj and libVLC, and packaging resources. |
 | `androidApp/src/main` | The Android application: `MainActivity`, `AndroidNextcloudServices`, Keystore-backed credentials, WorkManager workers, `NextcloudDocumentsProvider`, folder sync, media backup, and share-target activities. |
-| `contractAcquisition` | A plain Kotlin/JVM module that verifies signed App Store packages and extracts app contracts. Both `androidApp` and the desktop target depend on it; `commonMain` does not. |
+| `contractAcquisition` | A plain Kotlin/JVM module that verifies signed App Store packages and extracts app contracts. `androidApp` and both `ui` JVM targets depend on it, so shared `jvmMain` code can translate its results; `commonMain` does not. |
 | `src/` (Rust crate) | The reference schema and descriptor compiler, plus the Windows Explorer shell registrar binary that the desktop Windows package bundles. The Rust compiler is not linked into the app. |
 
 `jvmMain` is not a separate Kotlin Multiplatform source set. The `ui` build adds
@@ -63,18 +65,20 @@ behaves identically on both JVM targets belongs in `ui/src/jvmMain`. Code that
 differs because of lifecycle, storage, or operating-system APIs stays in the
 platform module, with the difference documented and tested.
 
-**Last reviewed: 2026-10-02.** This is a source inventory, not a plan. The code
+**Last reviewed: 2026-10-17.** This is a source inventory, not a plan. The code
 may have changed since; the default branch is the source of truth. Similarity
-figures came from comparing function bodies after removing the `Android` and
-`Desktop` name prefixes.
+figures came from comparing function bodies on 2026-10-02 after removing the
+`Android` and `Desktop` name prefixes, and were not remeasured on the review
+date.
 
 **Already shared.** All Compose UI, the sync domain model (planning,
 conflicts, checkpoints), groupware and media DAV models, virtual-file eviction
 policy, and the `NextcloudPlatformServices` interface live in `commonMain`.
 Both service containers implement that interface. `jvmMain` shares login and
-authenticated request policy, application read sessions, detached downloads,
-the resumable chunk-upload state machine, staging-space reservations, support
-diagnostics and intake, text-draft encryption, and WebDAV href decoding.
+authenticated request policy, application read sessions, App Store contract
+acquisition results and failures, detached downloads, the resumable
+chunk-upload state machine, staging-space reservations, support diagnostics and
+intake, text-draft encryption, and WebDAV href decoding.
 
 **Still duplicated.** The gap is below the shared interface: each platform has
 its own HTTP request code, protocol adapters, XML parsers, and sync executor.
@@ -89,7 +93,7 @@ its own HTTP request code, protocol adapters, XML parsers, and sync executor.
 | Medium | Dynamic discovery cache. Most of the logic is identical | `AndroidDynamicDiscoveryCache.kt` | `DesktopDynamicDiscoveryCache.kt` | One `jvmMain` cache |
 | Medium | Deck card draft codec, capacity, and migration policy | `AndroidDeckCardDraftStore.kt` | `DesktopDeckCardDraftStore.kt` | `commonMain` policy behind a storage port |
 | Medium | File read cache. Android skips leased entries during eviction; desktop eviction has no lease check | `AndroidFileReadCache.kt`, `AndroidVirtualFileCache.kt` | `DesktopFileReadCache.kt` | A `jvmMain` blob store |
-| Medium | Account removal stages and journals | Five `AndroidAccountRemoval*` files | `DesktopAccountRemoval.kt` | A `commonMain` removal state machine |
+| Medium | Account removal stages and journals | Four `AndroidAccountRemoval*` files | `DesktopAccountRemoval.kt` | A `commonMain` removal state machine |
 | Medium | Pure policy kept in platform code | `AndroidFileSyncContentEvidence.kt` | `DesktopFileSyncRetryPolicy.kt`, `DesktopFileSyncBatchResult.kt`, `DesktopFileSyncContentSlices.kt` | `commonMain` |
 | Low | Small identical helpers: streaming multipart body, document-editing capability parsing, bounded reads, `sha256Hex` copies, update-channel preferences | Several files | Several files | `jvmMain` |
 

androidApp/build.gradle.kts

@@ -110,6 +110,19 @@ dependencies {
     androidTestImplementation("com.squareup.okhttp3:okhttp-tls:5.4.0")
 }
 
+// ContractModuleAndroidJsonApiTest compares the contract module's org.json references with the
+// platform's own org.json, so unit tests receive the compileSdk boot classpath from the plugin.
+// It is read when the test starts, after the plugin has finalized the compile options.
+val androidSdkComponents = androidComponents.sdkComponents
+tasks.withType<Test>().configureEach {
+    jvmArgumentProviders.add(
+        CommandLineArgumentProvider {
+            val entries = androidSdkComponents.bootClasspath.get().joinToString(File.pathSeparator) { it.asFile.absolutePath }
+            listOf("-Dnative.androidBootClasspath=$entries")
+        },
+    )
+}
+
 val validateReleaseSigning by tasks.registering {
     group = "verification"
     description = "Requires complete protected signing input before producing release artifacts."

androidApp/src/androidTest/kotlin/dev/obiente/nextcloudnative/AppOwnedOpenApiAndroidInstrumentedTest.kt

@@ -1,7 +1,22 @@
 package dev.obiente.nextcloudnative
 
 import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import dev.obiente.nextcloudnative.app.AppStoreContractAcquisition
+import dev.obiente.nextcloudnative.app.AppStoreContractAcquisitionException
+import dev.obiente.nextcloudnative.app.AppStoreContractFailureKind
+import dev.obiente.nextcloudnative.app.AppStoreContractRequest
+import dev.obiente.nextcloudnative.app.AppStoreContractUnavailableReason
+import dev.obiente.nextcloudnative.app.acquireAppStoreContract
+import dev.obiente.nextcloudnative.contracts.FileAppStoreCatalogCache
+import dev.obiente.nextcloudnative.contracts.SignedAppStoreContractAcquirer
+import java.io.File
 import java.lang.reflect.Method
+import mockwebserver3.MockResponse
+import mockwebserver3.MockWebServer
+import okhttp3.OkHttpClient
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
 import org.junit.Assert.assertFalse
 import org.junit.Assert.assertTrue
 import org.junit.Test
@@ -35,6 +50,71 @@ class AppOwnedOpenApiAndroidInstrumentedTest {
         }
     }
 
+    @Test
+    fun everyContractStaticInitializerAndFailureBoundaryWorkOnAndroid() {
+        // Initialize each packaged top-level facade and companion owner on ART and ICU. The JVM
+        // unit test ContractModuleInitializationTest fails when a facade is missing from this list.
+        listOf(
+            "AppOwnedOpenApiContractKt", "AppStoreCatalogCacheKt", "AppStoreCatalogReleasesKt",
+            "ContractAcquisitionFailureKt", "ContractAcquisitionOutcomeKt", "JsonEquivalenceKt", "LinkedSourceArchiveKt",
+            "NextcloudAppPackageTrustVerifierKt", "OpenApiYamlParserKt", "SignedAppStoreContractAcquirerKt",
+            "SignedPackageTarReaderKt", "StaticPhpParametersKt", "StaticRouteContractKt", "StrictJsonValuesKt",
+            "TarArchivePathKt", "VerifiedChoresContractKt", "VerifiedContractCacheKt", "VerifiedExactWriteAdaptersKt",
+            "SignedAppStoreContractAcquirer",
+            "FileAppStoreCatalogCache", "DynamicApiResponseCache", "FileVerifiedContractCache",
+        ).forEach { name -> Class.forName("dev.obiente.nextcloudnative.contracts.$name") }
+        Class.forName("dev.obiente.nextcloudnative.app.JvmAppStoreContractAcquisitionKt")
+
+        val failed = try {
+            acquireAppStoreContract(AppStoreContractRequest("example", "34.0.3", "1.0.0")) { _, _ ->
+                throw NoClassDefFoundError("dev.obiente.nextcloudnative.contracts.SyntheticKt")
+            }
+            null
+        } catch (failure: AppStoreContractAcquisitionException) {
+            failure
+        }
+        assertEquals(AppStoreContractFailureKind.RuntimeIncompatible, failed?.kind)
+        assertFalse(failed?.message.orEmpty().contains("SyntheticKt"))
+    }
+
+    @Test
+    fun realCatalogPathAndYamlParserWorkOnAndroid() {
+        val cacheRoot = File(InstrumentationRegistry.getInstrumentation().targetContext.cacheDir, "catalog-cache-test")
+        cacheRoot.deleteRecursively()
+        // A regular file where the cache directory belongs makes catalog publication fail on ART.
+        check(cacheRoot.mkdirs() && File(cacheRoot, "blocked").createNewFile())
+        try {
+            MockWebServer().use { server ->
+                server.start()
+                repeat(2) { server.enqueue(MockResponse(body = """[{"id":"other","certificate":"c","releases":[]}]""")) }
+                val acquirer = SignedAppStoreContractAcquirer(
+                    httpClient = OkHttpClient(),
+                    appStoreBaseUrl = server.url("api/v1").toString(),
+                    requireHttps = false,
+                    catalogCache = FileAppStoreCatalogCache(File(File(cacheRoot, "blocked"), "catalogs")),
+                )
+                val outcome = acquireAppStoreContract(
+                    AppStoreContractRequest("example", "34.0.3", "1.0.0"),
+                    acquirer::acquireOutcome,
+                )
+                assertEquals(
+                    AppStoreContractAcquisition.Unavailable(AppStoreContractUnavailableReason.NoMatchingRelease),
+                    outcome,
+                )
+                assertEquals(2, server.requestCount)
+            }
+        } finally {
+            cacheRoot.deleteRecursively()
+        }
+
+        val parseYaml = Class.forName("dev.obiente.nextcloudnative.contracts.OpenApiYamlParserKt")
+            .getDeclaredMethod("parseYamlObject", String::class.java)
+        val yaml = "openapi: 3.0.1\nservers: [{ url: /apps/example }]\npaths:\n  /items: {}\n"
+        val document = parseYaml.invoke(null, yaml) as JSONObject
+        assertEquals("3.0.1", document.optString("openapi"))
+        assertTrue(document.getJSONObject("paths").has("/items"))
+    }
+
     private fun Method.accepts(server: String): Boolean {
         val document = """{"openapi":"3.1.1","servers":[{"url":"$server"}],"paths":{"/items":{}}}"""
         return invoke(null, "example", "openapi.json", document) as Boolean

androidApp/src/main/kotlin/dev/obiente/nextcloudnative/AndroidNextcloudServices.kt

@@ -13,9 +13,9 @@ import android.provider.DocumentsContract
 import android.provider.Settings
 import android.util.Base64
 import android.util.Log
-import dev.obiente.nextcloudnative.app.AcquiredOpenApiContract
-import dev.obiente.nextcloudnative.app.AcquiredOpenApiContractSourceKind
-import dev.obiente.nextcloudnative.app.AcquiredContractKind
+import dev.obiente.nextcloudnative.app.AppStoreContractAcquisition
+import dev.obiente.nextcloudnative.app.AppStoreContractRequest
+import dev.obiente.nextcloudnative.app.acquireAppStoreContract
 import dev.obiente.nextcloudnative.app.DeckAttachment
 import dev.obiente.nextcloudnative.app.DeckAttachmentOpenTarget
 import dev.obiente.nextcloudnative.app.DeckCardDraftKey
@@ -230,13 +230,10 @@ import dev.obiente.nextcloudnative.app.parseTalkMessageJson
 import dev.obiente.nextcloudnative.app.requireSafe
 import dev.obiente.nextcloudnative.app.systemTagsDavDiscoveryRequest
 import dev.obiente.nextcloudnative.app.toWebDavMutationSpec
-import dev.obiente.nextcloudnative.contracts.ContractAcquisitionRequest
 import dev.obiente.nextcloudnative.contracts.CachedDynamicApiResponse
-import dev.obiente.nextcloudnative.contracts.OpenApiContractSourceKind
 import dev.obiente.nextcloudnative.contracts.FileAppStoreCatalogCache
 import dev.obiente.nextcloudnative.contracts.FileVerifiedContractCache
 import dev.obiente.nextcloudnative.contracts.SignedAppStoreContractAcquirer
-import dev.obiente.nextcloudnative.contracts.VerifiedContractKind
 import java.io.File
 import java.io.ByteArrayOutputStream
 import java.io.FileInputStream
@@ -2959,40 +2956,8 @@ internal class AndroidNextcloudServices(
         NextcloudApiResponse(response.status, response.body, response.contentType, response.etag, response.location)
     }
 
-    override suspend fun acquireSignedOpenApiContract(
-        appId: String,
-        serverVersion: String,
-        installedAppVersion: String?,
-    ): AcquiredOpenApiContract? = withContext(Dispatchers.IO) {
-        contractAcquirer.acquire(ContractAcquisitionRequest(appId, serverVersion, installedAppVersion))
-            ?.let { contract ->
-                AcquiredOpenApiContract(
-                    appId = contract.appId,
-                    appVersion = contract.appVersion,
-                    contractVersion = contract.contractVersion,
-                    specFile = contract.specFile,
-                    document = contract.document,
-                    packageUrl = contract.packageUrl,
-                    sourceUrl = contract.sourceUrl,
-                    sourceKind = when (contract.sourceKind) {
-                        OpenApiContractSourceKind.SignedAppPackage ->
-                            AcquiredOpenApiContractSourceKind.SignedAppPackage
-                        OpenApiContractSourceKind.SignedCompatibleAppPackage ->
-                            AcquiredOpenApiContractSourceKind.SignedCompatibleAppPackage
-                        OpenApiContractSourceKind.AppStoreLinkedExactGitHubTag ->
-                            AcquiredOpenApiContractSourceKind.AppStoreLinkedExactGitHubTag
-                        OpenApiContractSourceKind.AppStoreLinkedCompatibleGitHubTag ->
-                            AcquiredOpenApiContractSourceKind.AppStoreLinkedCompatibleGitHubTag
-                    },
-                    contractKind = when (contract.contractKind) {
-                        VerifiedContractKind.OpenApi -> AcquiredContractKind.OpenApi
-                        VerifiedContractKind.VerifiedReadRoutes -> AcquiredContractKind.VerifiedReadRoutes
-                        VerifiedContractKind.OpenApiWithVerifiedReadRoutes ->
-                            AcquiredContractKind.OpenApiWithVerifiedReadRoutes
-                    },
-                )
-            }
-    }
+    override suspend fun acquireSignedOpenApiContract(request: AppStoreContractRequest): AppStoreContractAcquisition =
+        withContext(Dispatchers.IO) { acquireAppStoreContract(request, contractAcquirer, ::recordSupportDiagnostic) }
 
     override suspend fun listActivities(
         session: NextcloudSession,