ADFA-4128 (4/11): quickbuild:runtime — swapping code in the running app

quickbuild/docs/reliability-gaps.md

@@ -13,7 +13,7 @@ relink-crash recovery gap.
 | Gap | What the user sees | Frequency | Blocks v1? |
 | --- | --- | --- | --- |
 | #89 | Red-alert icon; tapping Quick Build does nothing until "Restart session" | No device repro `[inferred]` | TBD |
-| #91 | Their own app crash is never surfaced; CoGo blames deploy infra | `[unmeasured]` | TBD |
+| #91 | Their own app crash is never surfaced; CoGo blames deploy infra | `[unmeasured]` | ADFA-5466 |
 | #87 | A one-line edit in a Room/KSP project runs a full ~200s rebuild + reinstall | 3/3 when attempted | TBD |
 | Relink crash | A reload that crashes the app repeats the crash at every process boot | Trigger fixed; net still absent | TBD |
 | Relink stuck | A failed relink re-fails on every later save until a gradle-file touch | `[unmeasured]` | No - fixed below |
@@ -52,7 +52,7 @@ flowchart LR
 ## #91 - an organic proxy-app crash never reaches the crash surface
 
 - **Root cause:** the runtime only reports a crash while a reload is in flight
-  (`QuickBuildRuntime.java:306` gates on `pendingReloadGeneration >= 0`, which is -1 between
+  (the crash guard gates on `FirstFrameGate.pending() >= 0`, which is -1 between
   builds). The disconnect *is* detected - `ProxyAppConnections.onDisconnected()` emits
   `TargetReport.Disconnected` - but the session manager's collector only tests for `Crashed`
   (`QuickBuildSessionManager.kt:281`). Today's entire user-visible consequence of a crash is an

quickbuild/runtime/build.gradle.kts

@@ -0,0 +1,105 @@
+import com.itsaky.androidide.build.config.BuildConfig
+
+plugins {
+	id("com.android.library")
+}
+
+description =
+	"Quick Build runtime embedded in generated proxy apps: binds to CoGo, receives payload fds, hot-reloads (ADFA-4128)"
+
+// CoGo stages this AAR into its assets and the device reads it by name, so pin the archive
+// name instead of inheriting the module name.
+base.archivesName.set("quickbuild-runtime")
+
+android {
+	namespace = "${BuildConfig.PACKAGE_NAME}.quickbuild.runtime"
+
+	defaultConfig {
+		// Runs inside apps BUILT WITH CoGo, not inside the IDE.
+		minSdk = BuildConfig.MIN_SDK_FOR_APPS_BUILT_WITH_COGO
+	}
+
+	compileOptions {
+		// Java-only and Java 8, like :logsender - the AAR is injected into user
+		// projects and must not drag kotlin-stdlib or any other dependency in.
+		sourceCompatibility = JavaVersion.VERSION_1_8
+		targetCompatibility = JavaVersion.VERSION_1_8
+	}
+
+	buildFeatures.apply {
+		aidl = true
+		viewBinding = false
+		buildConfig = false
+	}
+}
+
+// JVM unit tests for the plain-Java payload logic (generation gate, metadata/component
+// map parsing, asset extraction). Mirrors :quick-build's jupiter setup.
+tasks.withType<Test> {
+	useJUnitPlatform()
+}
+
+// DoD coverage gate: >=90% line+branch on non-UI (domain/data) code.
+// Same shape as :quick-build's report: the root build attaches the jacoco agent to
+// every Test task, and for Android modules the exec lands at
+// build/outputs/unit_test_code_coverage/<variant>UnitTest/, NOT build/jacoco/ -- a
+// JacocoReport pointed at build/jacoco/ silently SKIPs and the gate is never
+// measured (ADFA-3834 learnings).
+tasks.register<JacocoReport>("jacocoTestReport") {
+	group = "verification"
+	description = "JaCoCo line+branch coverage for the v8Debug unit tests."
+	dependsOn("testV8DebugUnitTest")
+
+	reports {
+		xml.required.set(true)
+		html.required.set(true)
+	}
+
+	// Java-only module: the hand-written surface is the javac output. The AIDL stubs
+	// (IQuickBuildHost/IQuickBuildTarget + nested Stub/Proxy/Default) are generated
+	// code, so they are excluded from the measured set.
+	//
+	// Device-only Android/binder glue is EXEMPT from the JVM coverage bar (DoD: >=90%
+	// line+branch on non-UI code; these classes only execute meaningfully on a device
+	// and are covered by the android-qa device walks instead). Anything JVM-testable
+	// stays in the measured set - notably LegacyResourceSwap's file half and all
+	// parsing/persistence code.
+	classDirectories.setFrom(
+		fileTree(
+			layout.buildDirectory.dir("intermediates/javac/v8Debug/compileV8DebugJavaWithJavac/classes"),
+		) {
+			exclude("com/itsaky/androidide/quickbuild/IQuickBuild*")
+			// Binder host service: payload fds, Handler/Looper, activity relaunch orchestration.
+			exclude("com/itsaky/androidide/quickbuild/runtime/QuickBuildRuntime*")
+			// ServiceConnection bind/reconnect to CoGo; binder death + rebind only happen on-device.
+			exclude("com/itsaky/androidide/quickbuild/runtime/QuickBuildClient*")
+			// Framework-instantiated AppComponentFactory (Activity/Service/Provider hooks).
+			exclude("com/itsaky/androidide/quickbuild/runtime/QuickBuildAppComponentFactory*")
+			// InMemoryDexClassLoader (ART-only) + /proc + android.os.Process boot path; not
+			// splittable without moving prod code around - the generation-gate logic it defers
+			// to (Generations, PayloadPersistence, PersistedSelection) is JVM-tested.
+			exclude("com/itsaky/androidide/quickbuild/runtime/PayloadStore*")
+			// API 30+ ResourcesLoader/ResourcesProvider attach; framework Resources objects only.
+			exclude("com/itsaky/androidide/quickbuild/runtime/ResourceStore*")
+			// Overlay banner View/TextView UI (UI is DoD-exempt; OverlayState text model is JVM-tested).
+			exclude("com/itsaky/androidide/quickbuild/runtime/StatusOverlay*")
+			// Application.ActivityLifecycleCallbacks census over real Activity instances.
+			exclude("com/itsaky/androidide/quickbuild/runtime/ActivityTracker*")
+		},
+	)
+	sourceDirectories.setFrom(files("src/main/java"))
+	executionData.setFrom(
+		layout.buildDirectory.file(
+			"outputs/unit_test_code_coverage/v8DebugUnitTest/testV8DebugUnitTest.exec",
+		),
+	)
+}
+
+dependencies {
+	testImplementation(libs.tests.junit.jupiter)
+	testImplementation(libs.tests.google.truth)
+	// Shared offline-guard scanner (OfflineNetworkGuardTest). Test-only: this never
+	// reaches the AAR, so the module's no-kotlin-stdlib rule still holds.
+	testImplementation(testFixtures(projects.quickbuild.protocol))
+	testRuntimeOnly(libs.tests.junit.platformLauncher)
+}

quickbuild/runtime/src/main/AndroidManifest.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+	<!--
+		Package visibility (API 30+ filtering): the proxy app binds CoGo's deploy service.
+		Declared here so every generated proxy app inherits it via manifest merge.
+	-->
+	<queries>
+		<package android:name="com.itsaky.androidide" />
+	</queries>
+
+	<!--
+		Do NOT declare android:appComponentFactory here: a debuggable app that also pulls
+		androidx.core (which declares androidx.core.app.CoreComponentFactory) then fails manifest
+		merge, and that happens BEFORE the proxy app build's merged-manifest transform runs. The
+		proxy app build owns the attribute instead - QuickBuildManifestTransformer sets it on the
+		MERGED manifest, adding it when absent and replacing a library-injected one. An
+		<application> ELEMENT is fine, and is what the keep-alive service below needs; only the
+		attribute is forbidden.
+	-->
+	<application>
+		<!--
+			Lets CoGo bind into this app so the cached-app freezer leaves it alone for the life of a
+			Quick Build session; without it the app is frozen ~1 min after it loses the foreground
+			and stops answering the reload handshake - see QuickBuildKeepAliveService. Exported
+			because CoGo is a different uid, with no intent-filter so it is reachable by explicit
+			component only, and named in the Gradle plugin's UNPROXIABLE_BY_NAME so the proxy-app
+			manifest transform leaves this name intact.
+		-->
+		<service
+			android:name="com.itsaky.androidide.quickbuild.runtime.QuickBuildKeepAliveService"
+			android:exported="true" />
+	</application>
+
+</manifest>

quickbuild/runtime/src/main/aidl/com/itsaky/androidide/quickbuild/IQuickBuildHost.aidl

@@ -0,0 +1,24 @@
+package com.itsaky.androidide.quickbuild;
+
+import com.itsaky.androidide.quickbuild.IQuickBuildTarget;
+
+/**
+ * CoGo side of the deploy channel (bound service, LogSender bind pattern). The proxy app
+ * binds on launch and registers its callback. CoGo verifies Binder.getCallingUid()
+ * against the proxy app's installed uid on every call.
+ */
+interface IQuickBuildHost {
+
+	/**
+	 * Register the proxy app. CoGo replies (possibly immediately) with an
+	 * {@link IQuickBuildTarget#onPayload} carrying the current generation when the
+	 * app's running generation is stale.
+	 */
+	void connect(IQuickBuildTarget target, String packageName, long runningGeneration);
+
+	/** The payload for {@code generation} was loaded and rendered in {@code reloadMillis}. */
+	oneway void reportReloaded(long generation, long reloadMillis);
+
+	/** The payload for {@code generation} crashed in render/lifecycle. */
+	oneway void reportCrash(long generation, String stackSummary);
+}

quickbuild/runtime/src/main/aidl/com/itsaky/androidide/quickbuild/IQuickBuildTarget.aidl

@@ -0,0 +1,46 @@
+package com.itsaky.androidide.quickbuild;
+
+/**
+ * Proxy app side of the deploy channel. CoGo calls this after a successful
+ * quick build. Payloads travel as ParcelFileDescriptors; nothing touches shared storage.
+ * The target accepts a payload only when {@code generation} is strictly newer than the
+ * generation it currently runs.
+ *
+ * Versioning: CoGo and an installed proxy app can run DIFFERENT revisions of this
+ * interface (the runtime AAR is baked into the proxy app at proxy app build time). Only ever
+ * APPEND methods at the end - never reorder or remove. An older proxy app's stub answers
+ * an unknown transaction code with "not handled", and because the interface is oneway
+ * the caller never notices; the message is simply ignored.
+ */
+oneway interface IQuickBuildTarget {
+
+	/**
+	 * Deliver generation {@code generation}.
+	 *
+	 * @param dexPayload      classes.dex containing ALL user classes + generated proxies,
+	 *                        or null for a resources/assets-only deploy.
+	 * @param resourcesPayload fd to the full relinked resource apk (resources.arsc plus
+	 *                        every compiled resource file, not a bare table - see
+	 *                        Aapt2Link's KDoc) for
+	 *                        ResourcesProvider.loadFromApk, or null when resources did
+	 *                        not change.
+	 * @param assetsPayload   a zip of changed asset files, or null.
+	 * @param metadataJson    JSON: entry activity class, changed-asset paths, flags.
+	 *                        Schema in quickbuild/protocol/README.md.
+	 */
+	void onPayload(long generation, in @nullable ParcelFileDescriptor dexPayload,
+			in @nullable ParcelFileDescriptor resourcesPayload,
+			in @nullable ParcelFileDescriptor assetsPayload, String metadataJson);
+
+	/**
+	 * Build-status message: tells the running proxy app that a quick build
+	 * FAILED CoGo-side (a compile error never produces a payload, so without this the
+	 * app would silently keep running old code with no user-visible signal), or that a
+	 * build succeeded (clears a previously shown failure).
+	 *
+	 * @param statusJson JSON with string-only values; schema in quickbuild/protocol/README.md.
+	 *                   Unknown kinds and unknown fields are ignored by the runtime, so
+	 *                   the schema can grow without breaking installed proxy apps.
+	 */
+	void onBuildStatus(String statusJson);
+}