build: add R8 shrink-survival module and ship consumer keep-rules

A library has to survive its consumers shrinking their own apps: any class or
member the SDK reaches reflectively or through an SPI can be tree-shaken or
renamed by R8/ProGuard unless the SDK tells the shrinker to keep it. Nothing in
the build verified that, and the SDK shipped no consumer rules at all.

Ship consumer keep-rules from each module that has a reflective or runtime-wired
surface, packaged under META-INF/proguard so a downstream R8/AGP build applies
them automatically:

  - sdk-core: the Io seam and IoProvider, the HttpClient/AsyncHttpClient and
    Serde SPIs, the immutable HTTP models and their builders, and the Tristate
    hierarchy plus the kotlin.Metadata needed for reflective binding.
  - sdk-io-okio3: the OkioIoProvider entry point.
  - sdk-transport-okhttp: the OkHttpTransport entry point and Builder, with
    dontwarn for OkHttp's optional TLS providers.
  - sdk-serde-jackson: the JacksonSerde entry point and the custom Tristate
    module, plus the wholesale Jackson databind/core/annotation keeps that
    reflection-heavy library needs (a stripped annotation enum otherwise fails
    Jackson's config initialiser).

Add a test-only, unpublished sdk-shrink-test module that turns those rules into
a regression guard. It bundles a small consumer program with the SDK and its
real runtime dependencies (Okio, OkHttp, Jackson, Kotlin stdlib, an SLF4J
binding) into one jar, runs R8 in full mode over it using the SHIPPED keep-rules
extracted straight from the SDK jars, then runs the shrunk program. The program
performs a real in-process HTTP round-trip through OkHttpTransport and a full
Tristate JSON round-trip through JacksonSerde, so the check proves the kept
members still function after shrinking rather than merely that the classes
remain. The R8 run is wired into check, so a plain build enforces it.

The module is excluded from the binary-compatibility snapshot
(apiValidation.ignoredProjects) and from the Kover coverage aggregate, since it
publishes nothing and contributes no coverage; ktlint, detekt, and explicit-API
remain on. R8 is pinned in the version catalog and fetched from a
group-restricted Google Maven repo, never entering a published artifact.

CI wiring is deferred until the CI workflow itself lands.

Author: OmarAlJarrah

build.gradle.kts

@@ -82,13 +82,28 @@ tasks.named("check") {
     dependsOn(tasks.named("koverVerify"))
 }
 
+// Keep the test-only shrink-survival module out of the binary-compatibility snapshot. It ships no
+// public artifact, so it needs no committed `.api` file; without this exclusion apiCheck would
+// demand one (and apiDump would generate a spurious snapshot for an unpublished module). Mirrors
+// how the module is also left out of the kover aggregate below.
+apiValidation {
+    ignoredProjects += "sdk-shrink-test"
+}
+
 allprojects {
     repositories {
         mavenCentral()
         maven {
             // For maven snapshots
             url = URI.create("https://oss.sonatype.org/content/repositories/snapshots/")
         }
+        // Google's Maven repo hosts R8 (com.android.tools:r8), used only by the test-only
+        // sdk-shrink-test module. Restricted to that group so it is not consulted for anything else.
+        google {
+            content {
+                includeModule("com.android.tools", "r8")
+            }
+        }
     }
 
     // Plugin application lives in each subproject's own `plugins {}` block — the old

gradle/libs.versions.toml

@@ -9,6 +9,9 @@ reactor = "3.8.5"
 netty = "4.2.13.Final"
 jackson = "2.18.2"
 junit-jupiter = "5.10.2"
+# R8 is used only by the test-only sdk-shrink-test module to verify the SDK survives consumer-side
+# shrinking. It is fetched from Google's Maven repo and never enters a published artifact.
+r8 = "8.9.35"
 kover = "0.9.8"
 binary-compatibility-validator = "0.16.3"
 ktlint-plugin = "12.1.1"
@@ -32,6 +35,7 @@ jackson-module-kotlin = { module = "com.fasterxml.jackson.module:jackson-module-
 jackson-datatype-jsr310 = { module = "com.fasterxml.jackson.datatype:jackson-datatype-jsr310", version.ref = "jackson" }
 jackson-datatype-jdk8 = { module = "com.fasterxml.jackson.datatype:jackson-datatype-jdk8", version.ref = "jackson" }
 junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit-jupiter" }
+r8 = { module = "com.android.tools:r8", version.ref = "r8" }
 
 [plugins]
 kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }

sdk-core/src/main/resources/META-INF/proguard/sdk-core.pro

@@ -0,0 +1,70 @@
+# Copyright (c) 2026 dexpace and Omar Aljarrah
+#
+# Licensed under the MIT License. See LICENSE in the project root.
+# SPDX-License-Identifier: MIT
+
+# Consumer ProGuard/R8 keep rules for sdk-core.
+#
+# R8 and the Android Gradle Plugin automatically apply any rules packaged under
+# META-INF/proguard/ in a dependency jar, so a downstream application that shrinks its
+# build inherits these without extra configuration. They protect the parts of the toolkit
+# that a shrinker cannot prove are reachable on its own:
+#
+#   * the SPI seams that callers wire at runtime (the I/O provider, the transport clients,
+#     the serde), whose implementations live in separate modules and are referenced only
+#     through interfaces; and
+#   * the immutable HTTP models and the Tristate type, which Jackson and other reflective
+#     serializers bind by walking constructors, accessors, and Kotlin metadata rather than
+#     through direct call sites the shrinker can see.
+
+# --- SPI contracts wired at runtime --------------------------------------------------
+
+# The single I/O seam. Io.installProvider(...) is the documented entry point and IoProvider
+# is implemented in an adapter module, so keep both surfaces intact.
+-keep class org.dexpace.sdk.core.io.Io { *; }
+-keep class org.dexpace.sdk.core.io.IoProvider { *; }
+
+# Transport SPIs. Concrete transports (e.g. OkHttpTransport) are reached only through these
+# interfaces, so the methods a caller invokes must survive.
+-keep class org.dexpace.sdk.core.client.HttpClient { *; }
+-keep class org.dexpace.sdk.core.client.AsyncHttpClient { *; }
+
+# Serde SPI. JacksonSerde and any other implementation are reached through these interfaces.
+-keep class org.dexpace.sdk.core.serde.Serde { *; }
+-keep class org.dexpace.sdk.core.serde.Serializer { *; }
+-keep class org.dexpace.sdk.core.serde.Deserializer { *; }
+
+# --- Immutable HTTP models and their builders ----------------------------------------
+
+# Request / Response and their nested builders are constructed and read reflectively by
+# serializers and assertion frameworks; preserving every member keeps the public surface
+# (factories, builder fluents, component accessors) callable after shrinking.
+-keep class org.dexpace.sdk.core.http.request.Request { *; }
+-keep class org.dexpace.sdk.core.http.request.Request$RequestBuilder { *; }
+-keep class org.dexpace.sdk.core.http.request.RequestBody { *; }
+-keep class org.dexpace.sdk.core.http.request.Method { *; }
+-keep class org.dexpace.sdk.core.http.response.Response { *; }
+-keep class org.dexpace.sdk.core.http.response.Response$ResponseBuilder { *; }
+-keep class org.dexpace.sdk.core.http.response.ResponseBody { *; }
+-keep class org.dexpace.sdk.core.http.response.Status { *; }
+-keep class org.dexpace.sdk.core.http.common.Headers { *; }
+-keep class org.dexpace.sdk.core.http.common.Headers$Builder { *; }
+-keep class org.dexpace.sdk.core.http.common.MediaType { *; }
+-keep class org.dexpace.sdk.core.http.common.CommonMediaTypes { *; }
+-keep class org.dexpace.sdk.core.http.common.Protocol { *; }
+
+# --- Tristate ------------------------------------------------------------------------
+
+# Tristate models the absent / null / present distinction a serializer must reconstruct from
+# the wire. The custom Jackson binding (shipped by sdk-serde-jackson) checks the runtime type
+# of each variant, so the sealed hierarchy and the Present payload accessor must remain.
+-keep class org.dexpace.sdk.core.serde.Tristate { *; }
+-keep class org.dexpace.sdk.core.serde.Tristate$Absent { *; }
+-keep class org.dexpace.sdk.core.serde.Tristate$Null { *; }
+-keep class org.dexpace.sdk.core.serde.Tristate$Present { *; }
+
+# Kotlin emits @Metadata on every class; reflective Kotlin tooling (including Jackson's Kotlin
+# module) reads it to recover constructor parameter names and nullability. Strip it and
+# data-class binding silently degrades, so keep the annotation across the toolkit.
+-keepattributes RuntimeVisibleAnnotations,AnnotationDefault
+-keep class kotlin.Metadata { *; }

sdk-io-okio3/src/main/resources/META-INF/proguard/sdk-io-okio3.pro

@@ -0,0 +1,11 @@
+# Copyright (c) 2026 dexpace and Omar Aljarrah
+#
+# Licensed under the MIT License. See LICENSE in the project root.
+# SPDX-License-Identifier: MIT
+
+# Consumer ProGuard/R8 keep rules for sdk-io-okio3.
+#
+# This module's only public surface is the OkioIoProvider singleton, installed at startup
+# via Io.installProvider(OkioIoProvider). A shrinker following the application from its own
+# entry points cannot always see that wiring, so keep the provider and its INSTANCE field.
+-keep class org.dexpace.sdk.io.OkioIoProvider { *; }

sdk-serde-jackson/src/main/resources/META-INF/proguard/sdk-serde-jackson.pro

@@ -0,0 +1,28 @@
+# Copyright (c) 2026 dexpace and Omar Aljarrah
+#
+# Licensed under the MIT License. See LICENSE in the project root.
+# SPDX-License-Identifier: MIT
+
+# Consumer ProGuard/R8 keep rules for sdk-serde-jackson.
+#
+# JacksonSerde is the public entry point (withDefaults() / from(ObjectMapper)). The module also
+# registers a custom module that teaches Jackson how to (de)serialize Tristate; both the entry
+# point and that module are reached reflectively through Jackson's module-registration and
+# bean-introspection machinery, so they must survive shrinking.
+-keep class org.dexpace.sdk.serde.jackson.JacksonSerde { *; }
+-keep class org.dexpace.sdk.serde.jackson.JacksonObjectMappers { *; }
+-keep class org.dexpace.sdk.serde.jackson.TristateModule { *; }
+
+# Jackson databind is reflection-heavy: it reads annotations, walks bean members, and resolves
+# parametric types at runtime, and its own config classes initialise from annotation enum
+# singletons (a stripped or renamed enum value surfaces as an NPE in SerializationConfig's static
+# initialiser). It is not meaningfully shrinkable without a hand-curated configuration, so the
+# conventional — and the only safe — consumer recommendation is to keep the databind, core, and
+# annotation packages wholesale, retain the attributes Jackson reflects over, and keep every
+# annotation enum intact.
+-keepattributes Signature,*Annotation*,EnclosingMethod,InnerClasses
+-keep class com.fasterxml.jackson.databind.** { *; }
+-keep class com.fasterxml.jackson.core.** { *; }
+-keep class com.fasterxml.jackson.annotation.** { *; }
+-keep enum com.fasterxml.jackson.** { *; }
+-dontwarn com.fasterxml.jackson.databind.ext.**

sdk-shrink-test/build.gradle.kts

@@ -0,0 +1,217 @@
+/*
+ * Copyright (c) 2026 dexpace and Omar Aljarrah
+ *
+ * Licensed under the MIT License. See LICENSE in the project root.
+ * SPDX-License-Identifier: MIT
+ */
+
+import java.io.ByteArrayOutputStream
+import java.io.File
+import java.util.zip.ZipFile
+
+plugins {
+    // Kotlin only — no kover, no maven-publish, no signing. This module produces no published
+    // artifact and contributes no coverage; it is a build-time regression guard. The root build
+    // therefore does NOT add it to the kover aggregate, and `apiValidation.ignoredProjects`
+    // (root build.gradle.kts) keeps it out of the binary-compatibility snapshot. Java-8 bytecode,
+    // explicit-API strict mode, ktlint, and detekt are all inherited from the root build and left
+    // ON — the shrink harness honours the same conventions as the published modules.
+    kotlin("jvm")
+}
+
+group = "org.dexpace"
+version = "0.0.1-alpha.1"
+
+// The shrink harness exercises the SDK exactly as a downstream consumer would: it depends on the
+// published modules (core, the Okio I/O adapter, the OkHttp transport, the Jackson serde) and
+// their real transitive runtime dependencies, then bundles the lot into a single program for R8
+// to shrink. MockWebServer drives a genuine in-process HTTP round-trip so the shrunk program
+// proves the transport still works end-to-end, not merely that its classes survived.
+dependencies {
+    implementation(project(":sdk-core"))
+    implementation(project(":sdk-io-okio3"))
+    implementation(project(":sdk-transport-okhttp"))
+    implementation(project(":sdk-serde-jackson"))
+    implementation(libs.okhttp.mockwebserver.junit5)
+
+    // SLF4J is compileOnly in the SDK, so a real consumer supplies the API plus a binding at
+    // runtime. The no-op binding (which transitively brings slf4j-api) is the lightest choice and
+    // matches what every transport test runtime already uses; it must be bundled into the shrink
+    // input jar or the shrunk program fails with NoClassDefFoundError: org/slf4j/LoggerFactory.
+    runtimeOnly(libs.slf4j.nop)
+
+    // R8 itself runs as an external tool (see the r8Shrink task), so it lives in its own resolvable
+    // configuration rather than on the program classpath.
+}
+
+// ---------------------------------------------------------------------------------------------
+// R8 shrink-survival pipeline
+//
+//   buildShrinkInputJar  -> fat jar: consumer program + SDK + okio + okhttp + jackson + stdlib
+//   r8Shrink             -> runs R8 in full mode over that jar with the SHIPPED consumer rules
+//   r8Run                -> runs the shrunk program and asserts it prints the success sentinel
+//
+// r8Run is wired into `check`, so a plain `./gradlew build` proves shrink-survival.
+// ---------------------------------------------------------------------------------------------
+
+// Isolated configuration holding only the R8 tool jar, fetched from Google's Maven repo (added
+// to the root allprojects { repositories } block). Keeping it separate means R8's own (large)
+// dependency closure never leaks onto the program classpath that gets shrunk.
+val r8Tool: Configuration by configurations.creating {
+    isCanBeConsumed = false
+    isCanBeResolved = true
+}
+
+dependencies {
+    r8Tool(libs.r8)
+}
+
+val shrinkBuildDir: Provider<Directory> = layout.buildDirectory.dir("r8")
+val shrinkInputJar: Provider<RegularFile> = shrinkBuildDir.map { it.file("consumer-all.jar") }
+val shrunkJar: Provider<RegularFile> = shrinkBuildDir.map { it.file("consumer-shrunk.jar") }
+
+// Kept in sync with ShrinkSurvivalApp.SUCCESS_SENTINEL. The build script cannot reference the
+// project's own compiled classes, so the literal is duplicated here; the app prints it and the
+// harness greps for it.
+val successSentinel = "SHRINK-SURVIVAL-OK"
+
+// The consumer rules each SDK module ships under META-INF/proguard. The harness feeds these to R8
+// explicitly (rather than relying on R8 to auto-discover them) so the run fails loudly if a module
+// ever stops shipping its rules — that is the regression this module guards.
+val shippedConsumerRulePaths: List<String> =
+    listOf(
+        "META-INF/proguard/sdk-core.pro",
+        "META-INF/proguard/sdk-io-okio3.pro",
+        "META-INF/proguard/sdk-transport-okhttp.pro",
+        "META-INF/proguard/sdk-serde-jackson.pro",
+    )
+
+// Bundle the consumer program and its entire runtime classpath into one jar — the program R8 will
+// shrink. Service-loader manifests are concatenated; other duplicates (e.g. repeated module
+// metadata, signature files) are dropped so the merged jar stays valid.
+val buildShrinkInputJar by tasks.registering(Jar::class) {
+    group = "shrink"
+    description = "Bundles the consumer program and its runtime classpath into the R8 input jar."
+
+    dependsOn(tasks.named("classes"))
+    destinationDirectory.set(shrinkBuildDir)
+    archiveFileName.set("consumer-all.jar")
+    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+
+    val runtimeClasspath = configurations.named("runtimeClasspath")
+    from(sourceSets.main.get().output)
+    from(runtimeClasspath.map { cfg -> cfg.map { if (it.isDirectory) it else zipTree(it) } })
+
+    // Drop signed-jar metadata that would otherwise make the merged jar fail verification, and
+    // module descriptors that are meaningless once everything is flattened onto the classpath.
+    exclude("META-INF/*.SF", "META-INF/*.DSA", "META-INF/*.RSA")
+    exclude("module-info.class", "META-INF/versions/**/module-info.class")
+
+    manifest {
+        attributes("Main-Class" to "org.dexpace.sdk.shrinktest.ShrinkSurvivalApp")
+    }
+}
+
+// Java toolchain used to RUN R8 (the tool is Java-11 bytecode) and as R8's `--lib` runtime image.
+// Java 8 program bytecode runs fine against an 11 boot image, so this does not change the program's
+// target. Resolved lazily so configuration does not force toolchain provisioning.
+val r8Launcher =
+    javaToolchains.launcherFor {
+        languageVersion.set(JavaLanguageVersion.of(11))
+    }
+
+val r8Shrink by tasks.registering(JavaExec::class) {
+    group = "shrink"
+    description = "Runs R8 in full mode over the consumer jar using the SDK's shipped keep-rules."
+
+    dependsOn(buildShrinkInputJar)
+    inputs.files(r8Tool)
+    inputs.file(shrinkInputJar)
+    inputs.file(layout.projectDirectory.file("src/r8/app-rules.pro"))
+    outputs.file(shrunkJar)
+
+    classpath = r8Tool
+    mainClass.set("com.android.tools.r8.R8")
+    javaLauncher.set(r8Launcher)
+
+    doFirst {
+        val inputJar = shrinkInputJar.get().asFile
+        val outputJar = shrunkJar.get().asFile
+        outputJar.parentFile.mkdirs()
+        outputJar.delete()
+
+        // Extract each shipped consumer-rules file out of the input jar and assert it is present.
+        // A missing file here is exactly the shrink-survival regression we want to catch.
+        val extractedRulesDir = shrinkBuildDir.get().dir("shipped-rules").asFile
+        extractedRulesDir.mkdirs()
+        val extractedRuleFiles = mutableListOf<File>()
+        ZipFile(inputJar).use { zip ->
+            shippedConsumerRulePaths.forEach { entryPath ->
+                val entry =
+                    zip.getEntry(entryPath)
+                        ?: error(
+                            "Shipped consumer keep-rules missing from the SDK on the classpath: " +
+                                "$entryPath. Every SDK module that has reflectively/SPI-reached " +
+                                "surface must ship its rules under META-INF/proguard.",
+                        )
+                val dest = File(extractedRulesDir, entryPath.substringAfterLast('/'))
+                zip.getInputStream(entry).use { input -> dest.outputStream().use { input.copyTo(it) } }
+                extractedRuleFiles += dest
+            }
+        }
+
+        // R8 needs a boot image to resolve java.* references; the launcher's JDK home serves as the
+        // `--lib` runtime image.
+        val jdkHome = r8Launcher.get().metadata.installationPath.asFile.absolutePath
+        val appRules = layout.projectDirectory.file("src/r8/app-rules.pro").asFile
+
+        val r8Args = mutableListOf("--release", "--classfile", "--output", outputJar.absolutePath)
+        r8Args += listOf("--lib", jdkHome)
+        extractedRuleFiles.forEach { r8Args += listOf("--pg-conf", it.absolutePath) }
+        r8Args += listOf("--pg-conf", appRules.absolutePath)
+        r8Args += inputJar.absolutePath
+        args = r8Args
+
+        logger.lifecycle(
+            "Running R8 over ${inputJar.name} with ${extractedRuleFiles.size} shipped rule " +
+                "file(s) + app rules",
+        )
+    }
+}
+
+val r8Run by tasks.registering(JavaExec::class) {
+    group = "shrink"
+    description = "Runs the R8-shrunk consumer program and asserts the SDK survived shrinking."
+
+    dependsOn(r8Shrink)
+    inputs.file(shrunkJar)
+    // A marker output so the task is up-to-date when nothing changed.
+    val resultMarker = shrinkBuildDir.map { it.file("r8-run-ok.txt") }
+    outputs.file(resultMarker)
+
+    // Run the shrunk classfiles directly; an 11 launcher executes the Java-8 program fine.
+    javaLauncher.set(r8Launcher)
+    mainClass.set("org.dexpace.sdk.shrinktest.ShrinkSurvivalApp")
+    // `files(...)` is lazy, so referencing the not-yet-produced shrunk jar at configuration time is
+    // fine — it is resolved when the task runs, after r8Shrink has created it.
+    classpath = files(shrunkJar)
+
+    val captured = ByteArrayOutputStream()
+    standardOutput = captured
+
+    doLast {
+        val output = captured.toString("UTF-8")
+        logger.lifecycle(output.trim())
+        check(output.contains(successSentinel)) {
+            "The R8-shrunk consumer did not print the success sentinel. The SDK did not survive " +
+                "shrinking with its shipped keep-rules. Program output was:\n$output"
+        }
+        resultMarker.get().asFile.writeText("ok\n")
+    }
+}
+
+// Make the shrink-survival check part of the normal build: `./gradlew build` (which runs `check`)
+// now bundles, shrinks, and runs the consumer, failing if the SDK does not survive R8.
+tasks.named("check") {
+    dependsOn(r8Run)
+}