[android][breaking] compile with kotlin 2.x and raise api / language version

platforms/android/AGENTS.md

@@ -43,7 +43,7 @@ The sample is a separate Gradle composite (`samples/MobileBuyIntegration/setting
 - **`-Xexplicit-api=strict`** is on (`lib/build.gradle`). Every public class, method, field, and property must have an explicit visibility modifier. "Accidentally public" is not a thing here. This is a consumer-protection rule — if you see a public-by-default declaration, it was deliberate.
 - **Max line length: 140** (detekt-enforced). Detekt config: `lib/detekt.config.yml`.
 - **Library JVM target: 1.8.** Intentional for consumer compatibility; don't raise without a major-version discussion.
-- **Library Kotlin version is pinned.** The `lib/build.gradle` plugin version and any `apiVersion` / `languageVersion` settings exist to keep consumer compatibility stable. A Kotlin major-version migration is a planned major-version event, not a casual dep bump.
+- **Library Kotlin `apiVersion` / `languageVersion` are pinned at 2.0.** Set in `lib/build.gradle` so the AAR's bytecode stays consumable by Kotlin 2.0+ projects even though the compiler itself is on a newer 2.x. Bumping this pin is the consumer-facing breaking change, not bumping the compiler - treat it as a planned major-version event.
 - **Prefer generated protocol models.** Before adding hand-written protocol DTOs, check the generated models in `lib/src/main/java/com/shopify/checkoutkit/Models.kt` and the OpenRPC schema. Use generated UCP/ECP types for wire payloads; reserve local DTOs for Android-internal transport helpers that are not represented in the schema.
 
 ## Public API surface
@@ -91,6 +91,6 @@ Publishing goes through GitHub Releases → the repo-root `.github/workflows/and
 
 ## Things not to touch without discussion
 
-- **Library Kotlin version pin.** Consumer compatibility floor; any migration is a deliberate major-version decision.
+- **Library Kotlin `apiVersion` / `languageVersion` pin (2.0).** Consumer compatibility floor; raising it is a deliberate major-version decision. The compiler version itself is not the lever.
 - **`minSdk` / JVM target.** Same story.
 - **`-Xexplicit-api=strict`.** Removing this would let implicit public declarations ship; keeping it is a consumer-protection invariant.

platforms/android/build.gradle

@@ -1,8 +1,8 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 plugins {
     id 'com.android.library' version '9.1.1' apply false
-    id 'org.jetbrains.kotlin.android' version '1.9.23' apply false
-    id 'org.jetbrains.kotlin.plugin.serialization' version '1.9.23' apply false
+    id 'org.jetbrains.kotlin.android' version '2.3.21' apply false
+    id 'org.jetbrains.kotlin.plugin.serialization' version '2.3.21' apply false
     id 'io.gitlab.arturbosch.detekt' version '1.23.8' apply false
     id 'org.jetbrains.kotlinx.binary-compatibility-validator' version '0.18.1'
 }

platforms/android/gradle.properties

@@ -17,24 +17,32 @@ org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
 android.useAndroidX=true
 # Kotlin code style for this project: "official" or "obsolete":
 kotlin.code.style=official
+# Do not let the Kotlin Gradle Plugin publish a stdlib dependency that tracks
+# the compiler version. The library intentionally compiles with a newer Kotlin
+# compiler while keeping its consumer floor at Kotlin 2.0.
+kotlin.stdlib.default.dependency=false
 # Enables namespacing of each library's R class so that its R class includes only the
 # resources declared in the library itself and none from the library's dependencies,
 # thereby reducing the size of the R class for that library
 android.nonTransitiveRClass=true
 android.nonFinalResIds=false
 # -----------------------------------------------------------------------------
-# Temporary AGP 9 opt-outs that keep the library compilable with Kotlin 1.9.23.
+# AGP 9 opt-outs — driven by API-validation tooling, NOT by Kotlin compiler version.
 #
-# The library is deliberately held at Kotlin 1.9.23 to maximise consumer
-# compatibility: consumers on older Kotlin toolchains can still build against
-# our AAR without metadata-version warnings or language/API-level breakage.
+# AGP 9 ships a built-in Kotlin plugin that replaces `org.jetbrains.kotlin.android`,
+# but neither of our API-validation options works with it for Android libraries:
 #
-# Both opt-outs will be removed in AGP 10 (~mid-2026). Before then, plan to
-# migrate to Kotlin 2.x as part of the next major library release, with
-# `apiVersion`/`languageVersion` pinned to 1.9 in lib/build.gradle to preserve
-# the same consumer contract. Revisit this block at that time.
+#  - binary-compatibility-validator (BCV) listens for the `kotlin-android` plugin
+#    id, which AGP's built-in path doesn't apply, so `:lib:apiCheck`/`:lib:apiDump`
+#    never register. Tracked upstream:
+#    https://github.com/Kotlin/binary-compatibility-validator/issues/312
+#  - KGP's experimental `abiValidation` DSL exists for JVM and Multiplatform but
+#    is not yet available on KotlinAndroidProjectExtension. Umbrella:
+#    https://youtrack.jetbrains.com/issue/KT-71172
+#
+# Until either lands (or AGP 10 forces the issue ~mid-2026), we stay on the
+# explicit `org.jetbrains.kotlin.android` plugin so BCV keeps gating public API.
 # -----------------------------------------------------------------------------
-# Keep the explicit org.jetbrains.kotlin.android plugin at 1.9.23.
 android.builtInKotlin=false
-# KGP 1.9.23 uses the old DSL types (BaseExtension) that AGP 9 removed.
+# KGP uses the old DSL types (BaseExtension) that AGP 9 removed.
 android.newDsl=false