@@ -101,20 +101,40 @@ android {
         }
     }
 
+    // Signing material is the maintainer's and lives nowhere in this repository:
+    // `local.properties` is gitignored, and `*.jks` is refused outright.
+    //
+    // The config is created only when a keystore is actually there, so that a
+    // release build is something anyone who clones this can run. Without it the
+    // APK comes out unsigned, which is the honest outcome — an unsigned APK
+    // cannot be installed by an ordinary user, and a build that failed instead
+    // would make "can this be built" and "can this be published" the same
+    // question when they are not.
+    val keystore = localProperties.getProperty("KEYSTORE_FILE")?.let { file(it) }?.takeIf { it.exists() }
+
     signingConfigs {
-        create("release") {
-            storeFile = file(localProperties.getProperty("KEYSTORE_FILE", "../keystore.jks"))
-            storePassword = localProperties.getProperty("KEYSTORE_PASSWORD", "")
-            keyAlias = localProperties.getProperty("KEY_ALIAS", "release")
-            keyPassword = localProperties.getProperty("KEY_PASSWORD", "")
+        if (keystore != null) {
+            create("release") {
+                storeFile = keystore
+                storePassword = localProperties.getProperty("KEYSTORE_PASSWORD", "")
+                keyAlias = localProperties.getProperty("KEY_ALIAS", "release")
+                keyPassword = localProperties.getProperty("KEY_PASSWORD", "")
+            }
         }
     }
 
     buildTypes {
         release {
             isMinifyEnabled = true
             isShrinkResources = true
-            signingConfig = signingConfigs.getByName("release")
+            // The maintainer's key when there is one, and the debug key when
+            // there is not. Not a shortcut: an APK signed with the debug key
+            // cannot be published — every store refuses it — so it cannot be
+            // mistaken for a release, while it *can* be installed, which is
+            // what makes the minified build testable at all. R8 is where this
+            // project's recurring failure mode lives, and a release artifact
+            // nobody can run is one nobody has run.
+            signingConfig = signingConfigs.findByName("release") ?: signingConfigs.getByName("debug")
             proguardFiles(
                 getDefaultProguardFile("proguard-android-optimize.txt"),
                 "proguard-rules.pro",
@@ -602,6 +622,129 @@ tasks.withType<Test>().configureEach {
     }
 }
 
+// ── The shipped release APK, checked as a file ──────────────────────────────
+// R8 is where this project's recurring failure mode lives — green build, green
+// lint, green tests, broken on the artifact nobody ran — and the JNI bridge is
+// the part a shrinker is most confidently wrong about. Nothing in Kotlin calls
+// `nativeInit`'s callbacks and nothing in C calls anything, so R8 sees an
+// unreferenced method on both sides and renames or removes it. The failure is
+// not a crash: `nativeInit` logs that a callback did not resolve and returns,
+// so the tunnel comes up and answers nothing.
+//
+// Running the instrumentation suite against the minified build was tried first
+// and abandoned. The two APKs are shrunk by two separate R8 runs, so the test
+// APK's calls are compiled against names the application no longer has, and the
+// keeps that fix *that* (`-keep class eu.nodepass.somewhere.**`) would also
+// keep every JNI entry point — masking exactly the mistake this is for.
+//
+// So the artifact is read instead of run. This is a stronger check for the
+// question asked: it inspects the file that would ship, rather than a variant
+// built to be testable.
+
+abstract class ReleaseArtifactChecksTask : DefaultTask() {
+    @get:InputFile
+    abstract val apk: RegularFileProperty
+
+    @get:Input
+    abstract val entryPoints: ListProperty<String>
+
+    @get:Input
+    abstract val requiredAbis: ListProperty<String>
+
+    @TaskAction
+    fun check() {
+        val dex = StringBuilder()
+        ZipFile(apk.get().asFile).use { zip ->
+            zip.entries().asSequence().filter { it.name.endsWith(".dex") }.forEach { entry ->
+                // Names live in the dex string table as plain UTF-8, so a
+                // substring search over the file answers "did this survive
+                // R8 under this name" without a dex parser.
+                zip.getInputStream(entry).use { dex.append(String(it.readBytes(), Charsets.ISO_8859_1)) }
+            }
+        }
+        val text = dex.toString()
+
+        // The libraries the file must carry, for the ABIs it claims to support.
+        // Modern packaging leaves them compressed and page-aligned inside the
+        // APK rather than extracting them at install, so the file is the only
+        // place this can be asked -- an install directory's `lib/` is empty on
+        // a perfectly working install.
+        val libraries =
+            ZipFile(apk.get().asFile).use { zip ->
+                zip
+                    .entries()
+                    .asSequence()
+                    .map { it.name }
+                    .filter { it.endsWith("libsomewhere_native.so") }
+                    .toList()
+            }
+        val missingAbis = requiredAbis.get().filterNot { abi -> libraries.any { it.contains("/$abi/") } }
+        if (missingAbis.isNotEmpty()) {
+            throw GradleException(
+                "the release APK carries no native library for ${missingAbis.joinToString()}",
+            )
+        }
+
+        val missing = entryPoints.get().filterNot { text.contains(it) }
+        if (missing.isNotEmpty()) {
+            throw GradleException(
+                "the release APK does not carry ${missing.size} JNI entry point(s): " +
+                    missing.joinToString() + "\n\n" +
+                    "R8 renamed or removed them, and the native library resolves them by name at " +
+                    "call time. Nothing crashes: nativeInit logs that a callback did not resolve " +
+                    "and returns, so the tunnel comes up and carries nothing. See " +
+                    "app/proguard-rules.pro.",
+            )
+        }
+        logger.lifecycle(
+            "release APK: ${apk.get().asFile.length()} bytes, " +
+                "${entryPoints.get().size} JNI entry points present under their own names, " +
+                "native libraries for ${requiredAbis.get().joinToString()}",
+        )
+    }
+}
+
+val releaseArtifactChecks =
+    tasks.register<ReleaseArtifactChecksTask>("checkReleaseArtifact") {
+        group = "verification"
+        description = "The shipped APK still carries the names the native library resolves."
+        dependsOn("assembleRelease")
+        apk.set(
+            layout.buildDirectory.file("outputs/apk/release/app-release.apk").flatMap { signed ->
+                layout.buildDirectory.file(
+                    if (signed.asFile.exists()) {
+                        "outputs/apk/release/app-release.apk"
+                    } else {
+                        "outputs/apk/release/app-release-unsigned.apk"
+                    },
+                )
+            },
+        )
+        entryPoints.set(
+            listOf(
+                // The Kotlin halves, which R8 can rename.
+                "eu/nodepass/somewhere/vpn/NativeBridge",
+                "eu/nodepass/somewhere/quic/QuicConnection",
+                "eu/nodepass/somewhere/quic/QuicStack",
+                // The names the C side looks up. `nativeInit` resolves the
+                // callbacks by name *and* signature, and a rename of either
+                // half breaks it silently.
+                "nativeInit",
+                "nativeInput",
+                "nativeTcpWrite",
+                "onTcpAccept",
+                "onTcpRecv",
+                "onUdpRecv",
+                "nativeOpen",
+                "nativeReceive",
+                "nativeWrite",
+                "nativeSendDatagram",
+                "nativeExportKeyingMaterial",
+            ),
+        )
+        requiredAbis.set(listOf("arm64-v8a", "x86_64"))
+    }
+
 val classpathConsistencyTasks =
     listOf("Debug" to "debug", "Release" to "release").map { (capitalised, lowercase) ->
         tasks.register<ClasspathConsistencyTask>("checkClasspathConsistency$capitalised") {
 
@@ -1,7 +1,47 @@
-# Keep kotlinx.serialization metadata for @Serializable classes.
+# R8 rules.
+#
+# Everything here is a thing R8 cannot see being used. That is the whole
+# category: a shrinker removes what nothing references, and a JNI entry point,
+# a reflective serializer lookup and a class loaded by name are all referenced
+# from somewhere R8 does not read. The failure mode is the one this project has
+# met three times in other forms — green build, green lint, green tests, broken
+# on the artifact nobody ran.
+
+# ── JNI ─────────────────────────────────────────────────────────────────────
+# The native library resolves these by name and signature at call time. R8 sees
+# no Kotlin caller for the C side's callbacks and no C caller for anything, so
+# without this it renames both halves of the bridge and `nativeInit` fails to
+# resolve its callbacks — which it reports by logging and returning, so the
+# tunnel comes up and answers nothing.
+# Duplicated from `proguard-android-optimize.txt` on purpose. Removing it
+# changes nothing today — measured — because the platform's default file
+# carries the same rule, and that is precisely why it is written out here: a
+# rule this project depends on should be visible in this project, not inherited
+# from a file that could change under it.
+-keepclasseswithmembernames,includedescriptorclasses class * {
+    native <methods>;
+}
+# **This one is load-bearing, and measured to be.** The callbacks C calls into
+# are ordinary Kotlin methods, not native ones, so the rule above does not
+# reach them: without this, `nativeTcpWrite`, `onTcpAccept`, `onTcpRecv` and
+# `onUdpRecv` all leave the APK.
+-keep class eu.nodepass.somewhere.vpn.NativeBridge { *; }
+-keep class eu.nodepass.somewhere.quic.QuicConnection { *; }
+-keep class eu.nodepass.somewhere.quic.QuicStack { *; }
+
+# ── kotlinx.serialization ───────────────────────────────────────────────────
+# Serializers are found by a generated companion R8 cannot trace to a caller.
 -keepattributes *Annotation*, InnerClasses
 -dontnote kotlinx.serialization.**
 -keepclassmembers class **$$serializer { *; }
 -keepclasseswithmembers class ** {
     kotlinx.serialization.KSerializer serializer(...);
 }
+
+# ── Compile-only annotations ────────────────────────────────────────────────
+# Test dependencies bring annotations whose own dependencies exist only at
+# compile time. Nothing loads them at runtime, and R8 refuses to shrink an APK
+# with references it cannot resolve unless told the absence is expected.
+-dontwarn javax.lang.model.element.**
+-dontwarn com.google.errorprone.annotations.**
+-dontwarn javax.annotation.**
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Installs the release APK and starts it.
+#
+# `checkReleaseArtifact` reads the file and answers "are the names still there".
+# This answers the other half: does the thing run. R8 breaks startup in ways a
+# name check cannot see — a reflective lookup with no keep, a Compose entry
+# point shrunk away, a resource the shrinker decided was unused — and all of
+# them present as a process that dies before anything is on screen.
+#
+# Not a substitute for the device suite, which runs against the debug build for
+# reasons recorded in app/build.gradle.kts. This is the minimum that can be said
+# about the artifact that would actually ship.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PROJECT="$(cd "$ROOT/.." && pwd)"
+APP_ID="eu.nodepass.somewhere"
+DEVICE="${NOWHERE_DEVICE:-}"
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+step() { printf '\n== %s ==\n' "$*"; }
+
+command -v adb >/dev/null || fail "adb is not on PATH"
+[ -n "$DEVICE" ] || DEVICE="$(adb devices | awk '$2=="device"{print $1; exit}')"
+[ -n "$DEVICE" ] || fail "no device; see scripts/device-connect.sh"
+
+APK="$PROJECT/app/build/outputs/apk/release/app-release.apk"
+[ -f "$APK" ] || APK="$PROJECT/app/build/outputs/apk/release/app-release-unsigned.apk"
+[ -f "$APK" ] || fail "no release APK; run ./gradlew assembleRelease"
+
+step "install $(basename "$APK")"
+adb -s "$DEVICE" uninstall "$APP_ID" >/dev/null 2>&1
+adb -s "$DEVICE" install -r "$APK" 2>&1 | tail -1 | grep -q Success \
+    || fail "the release APK would not install. An unsigned APK cannot be; see the signing config."
+
+step "start it"
+adb -s "$DEVICE" logcat -c
+adb -s "$DEVICE" shell am start -n "$APP_ID/.MainActivity" >/dev/null 2>&1 \
+    || fail "the launcher activity would not start"
+sleep 6
+
+step "did it survive"
+CRASH="$(adb -s "$DEVICE" logcat -d 2>/dev/null | grep -E "FATAL EXCEPTION|AndroidRuntime: .*$APP_ID" | head -5)"
+[ -z "$CRASH" ] || { echo "$CRASH"; fail "the release build crashed on startup"; }
+
+PID="$(adb -s "$DEVICE" shell pidof "$APP_ID" 2>/dev/null | tr -d '\r ')"
+[ -n "$PID" ] || fail "the process is not running six seconds after start"
+echo "OK  running as pid $PID"
+
+# Deliberately not checked here, twice over.
+#
+# `System.loadLibrary` runs when the tunnel starts or the QUIC stack is first
+# touched, so a freshly opened screen has none of it mapped -- there is nothing
+# to look for. And a modern APK does not extract its native libraries at all:
+# they stay page-aligned inside the file and are mapped from there, so
+# `lib/arm64` under the install directory is empty on a working install. Both of
+# those were checked here first and both reported a failure that was the check's
+# rather than the app's.
+#
+# What the APK carries is `checkReleaseArtifact`'s, which reads the file.
+
+echo
+echo "PASS: the release APK installs, starts, and is still running six seconds"
+echo "      later."