stim 1.20.2 → 1.21.0

package/dist/native-android-JACyjTZs.mjs

@@ -0,0 +1,844 @@
+import { t as getExecutor } from "./exec-_UbtCQcG.mjs";
+import { d as workspaceDir, i as sharedBuildCache } from "./paths-DQtTgsBf.mjs";
+import { J as validateDeviceSlot, U as deviceSlotPlatforms, p as getProject } from "./config-CYcBF478.mjs";
+import { Gt as childEnvironment, tt as settingValueAt } from "./settings-CsJDEXgK.mjs";
+import { r as register } from "./cache-manifest-DkkqguoK.mjs";
+import { Y as statsProjectKey } from "./budget-Bs6SxxzO.mjs";
+import { d as runCancellationSignal } from "./native-run-DY_RLx3C.mjs";
+import { h as resolveBuild, n as buildCacheKey, o as entryDir, t as artifactIn } from "./build-cache-DmyR9Zzc.mjs";
+import { J as pickDefaultSystemImage, P as listInstalledSystemImages, R as ownedAvdDeviceProfile, T as findBuildTool, W as ownedAvdSystemImage, l as androidSystemImageAbi, o as androidHome, z as ownedAvdDirectory } from "./android-DUYkNF4u.mjs";
+import { o as resolveCcache } from "./ccache-BJRZ9pG3.mjs";
+import { r as androidToolchainAsync } from "./toolchain-Hp9sCpK4.mjs";
+import { n as fingerprintNativeInputs } from "./native-inputs-TRTTTRxt.mjs";
+import { a as nativeGradleTransfer, r as nativeGradleLocalSourceDigest, t as gradleOffloadInputs } from "./native-gradle-inputs-Bep9JcSF.mjs";
+import { d as buildGradle, l as androidSdkRefusal } from "./react-native-build-rhk4smwQ.mjs";
+import { a as explainBuildMiss, c as skippedMissReason } from "./prebuild-uD_ipCxF.mjs";
+import { c as resolveAndroidRunPlan } from "./result-DNiS-tTP.mjs";
+import { n as androidProcessRuntime } from "./launch-CD1yVc7U.mjs";
+import { n as planFlagRefusal, r as planPayload } from "./build-plan-CaFskB7_.mjs";
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync, readFileSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { storeArtifactAsync } from "@stim-cli/core";
+import { fileURLToPath } from "node:url";
+import { mkdtemp, open, readFile, readdir, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+//#region src/integrations/native-android-cache.ts
+const RECEIPT$1 = "native-android.json";
+async function digest(path, signal) {
+	const hash = createHash("sha256");
+	for await (const chunk of createReadStream(path, { signal })) hash.update(chunk);
+	return hash.digest("hex");
+}
+async function inspectApk(path, sdk, abi, operation, signal) {
+	signal?.throwIfAborted();
+	if (!(await stat(path)).isFile()) throw new Error("The native APK is not a regular file.");
+	const signer = findBuildTool(["apksigner"], { home: sdk });
+	const aapt = findBuildTool(["aapt"], { home: sdk });
+	if (!signer || !aapt) throw new Error("Android SDK apksigner and aapt are required to verify a cached native APK.");
+	const before = await digest(path, signal);
+	const options = {
+		timeoutMs: 3e4,
+		signal,
+		declareFor: operation
+	};
+	const executor = getExecutor();
+	const signers = [...(await executor.runFileAsync(signer.path, [
+		"verify",
+		"--print-certs",
+		path
+	], options)).matchAll(/^(?:Signer #\d+|V\d+(?:\.\d+)? Signer:) certificate SHA-256 digest: ([a-f\d]{64})\s*$/gim)].flatMap((match) => match[1] ? [match[1].toLowerCase()] : []).toSorted();
+	if (!signers.length) throw new Error("The native APK has no verified signing certificate.");
+	const badging = await executor.runFileAsync(aapt.path, [
+		"dump",
+		"badging",
+		path
+	], options);
+	const line = badging.split(/\r?\n/).find((value) => value.startsWith("package:"));
+	const androidPackage = line?.match(/^package: name='([A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)+)'/)?.[1];
+	if (!line || !androidPackage || /\bsplit=/.test(line)) throw new Error("The native APK is not a standalone Android package.");
+	const native = badging.split(/\r?\n/).find((value) => value.startsWith("native-code:"));
+	const abis = native ? [...native.matchAll(/'([^']+)'/g)].flatMap((match) => match[1] ? [match[1]] : []).toSorted() : [];
+	if (abi && native && !abis.includes(abi)) throw new Error("The native APK does not contain the target ABI.");
+	const sha256 = await digest(path, signal);
+	if (sha256 !== before) throw new Error("The native APK changed during verification.");
+	return {
+		androidPackage,
+		signers,
+		abis,
+		sha256
+	};
+}
+async function verifiedNativeApk(key, path, sdk, abi, operation, signal) {
+	try {
+		const receipt = JSON.parse(await readFile(join(dirname(path), RECEIPT$1), {
+			encoding: "utf8",
+			signal
+		}));
+		if (receipt.schema !== 1 || receipt.key !== key || receipt.sha256 !== await digest(path, signal)) return null;
+		const actual = await inspectApk(path, sdk, abi, operation, signal);
+		if (actual.sha256 !== receipt.sha256 || actual.androidPackage !== receipt.androidPackage || JSON.stringify(actual.signers) !== JSON.stringify(receipt.signers) || JSON.stringify(actual.abis) !== JSON.stringify(receipt.abis)) return null;
+		return actual;
+	} catch {
+		signal?.throwIfAborted();
+		return null;
+	}
+}
+async function materializeNativeApk(key, path, sdk, abi, operation, signal = runCancellationSignal(operation) ?? operation?.signal ?? getExecutor().reportSignal?.()) {
+	const actual = await verifiedNativeApk(key, path, sdk, abi, operation, signal);
+	return actual ? {
+		apkPath: path,
+		directory: null,
+		androidPackage: actual.androidPackage
+	} : null;
+}
+function nativeAndroidCache(sdk, abi, androidPackage, operation) {
+	return {
+		resolve: ({ key }) => resolveBuild("android", key),
+		async store({ key, sourcePath, overwrite, signal }) {
+			const expectedPackage = androidPackage();
+			const actual = expectedPackage === null ? await verifiedNativeApk(key, sourcePath, sdk, abi, operation, signal) : await inspectApk(sourcePath, sdk, abi, operation, signal);
+			if (!actual) throw new Error("The native APK has no matching verified cache receipt.");
+			if (expectedPackage !== null && actual.androidPackage !== expectedPackage) throw new Error("The APK package does not match the Gradle model.");
+			register({
+				dir: sharedBuildCache(),
+				name: "Build cache",
+				prune: "entries",
+				entriesDepth: 2,
+				note: "built .app/.apk keyed on the native fingerprint"
+			});
+			return storeArtifactAsync(entryDir("android", key), sourcePath, {
+				signal,
+				overwrite,
+				runFile: (file, args) => getExecutor().runFileAsync(file, args, {
+					timeoutMs: 12e4,
+					signal,
+					declareFor: operation
+				}),
+				async writeMetadata(staging) {
+					if (await digest(join(staging, basename(sourcePath)), signal) !== actual.sha256) throw new Error("The native APK changed while it was copied.");
+					await writeFile(join(staging, RECEIPT$1), JSON.stringify({
+						schema: 1,
+						key,
+						...actual
+					}), { signal });
+				}
+			});
+		}
+	};
+}
+async function plannedNativeApk(key, sdk, abi, operation) {
+	const path = artifactIn(entryDir("android", key));
+	return path !== null && await materializeNativeApk(key, path, sdk, abi, operation) !== null;
+}
+//#endregion
+//#region src/integrations/native-android-file-cache.ts
+const MAGIC = Buffer.from("STIMAPK1\n");
+const HEADER_BYTES = MAGIC.length + 4;
+const MAX_RECEIPT_BYTES = 1048576;
+const RECEIPT = "native-android.json";
+const fileKey = (key) => `native-android/v1/${key}`;
+async function readExactly(file, size, position, signal) {
+	const buffer = Buffer.alloc(size);
+	let offset = 0;
+	while (offset < size) {
+		signal.throwIfAborted();
+		const { bytesRead } = await file.read(buffer, offset, size - offset, position + offset);
+		if (!bytesRead) throw new Error("The shared native APK entry is truncated.");
+		offset += bytesRead;
+	}
+	return buffer;
+}
+async function unpack(source, directory, signal) {
+	const file = await open(source, "r");
+	try {
+		const header = await readExactly(file, HEADER_BYTES, 0, signal);
+		const size = header.readUInt32BE(MAGIC.length);
+		if (!header.subarray(0, MAGIC.length).equals(MAGIC) || size === 0 || size > MAX_RECEIPT_BYTES) throw new Error("The shared native APK entry has an unsupported header.");
+		const receipt = await readExactly(file, size, HEADER_BYTES, signal);
+		const apk = join(directory, "artifact.apk");
+		await writeFile(join(directory, RECEIPT), receipt, {
+			flag: "wx",
+			mode: 384,
+			signal
+		});
+		await pipeline(file.createReadStream({
+			start: HEADER_BYTES + size,
+			autoClose: false
+		}), createWriteStream(apk, {
+			flags: "wx",
+			mode: 384
+		}), { signal });
+		return apk;
+	} finally {
+		await file.close();
+	}
+}
+function nativeAndroidFileCache(files, sdk, abi, operation) {
+	return {
+		async resolve({ key, destinationDir, signal }) {
+			const directory = await mkdtemp(join(destinationDir, "native-apk-"));
+			let keep = false;
+			try {
+				const source = await files.resolve({
+					key: fileKey(key),
+					destinationDir: directory,
+					signal
+				});
+				if (!source) return null;
+				const contained = relative(await realpath(directory), await realpath(source));
+				if (isAbsolute(contained) || contained === ".." || contained.startsWith(`..${sep}`)) throw new Error("The shared native APK file is outside its download directory.");
+				if (!(await stat(source)).isFile()) throw new Error("The shared native APK entry is not a regular file.");
+				const apk = await unpack(source, await mkdtemp(join(directory, "unpacked-")), signal);
+				if (!await materializeNativeApk(key, apk, sdk, abi, operation, signal)) throw new Error("The shared native APK does not match its verification receipt.");
+				keep = true;
+				return apk;
+			} finally {
+				if (!keep) await rm(directory, {
+					recursive: true,
+					force: true
+				});
+			}
+		},
+		async store({ key, sourcePath, overwrite, signal }) {
+			const cached = artifactIn(entryDir("android", key));
+			if (!cached) throw new Error("No native APK is stored locally for this key.");
+			const metadata = await readFile(join(dirname(cached), RECEIPT), { signal });
+			if (metadata.length > MAX_RECEIPT_BYTES) throw new Error("The native APK receipt is too large.");
+			const receipt = JSON.parse(metadata.toString("utf8"));
+			if (receipt.schema !== 1 || receipt.key !== key) throw new Error("The native APK has no matching cache receipt.");
+			const directory = await mkdtemp(join(tmpdir(), "stim-native-apk-file-"));
+			try {
+				const envelope = join(directory, "artifact");
+				const header = Buffer.alloc(HEADER_BYTES);
+				MAGIC.copy(header);
+				header.writeUInt32BE(metadata.length, MAGIC.length);
+				const payload = async function* () {
+					yield header;
+					yield metadata;
+					const hash = createHash("sha256");
+					for await (const chunk of createReadStream(sourcePath, { signal })) {
+						hash.update(chunk);
+						yield chunk;
+					}
+					if (hash.digest("hex") !== receipt.sha256) throw new Error("The native APK changed while its shared entry was packed.");
+				};
+				await pipeline(Readable.from(payload()), createWriteStream(envelope, {
+					flags: "wx",
+					mode: 384
+				}), { signal });
+				signal.throwIfAborted();
+				await files.store({
+					key: fileKey(key),
+					sourcePath: envelope,
+					overwrite,
+					signal
+				});
+			} finally {
+				await rm(directory, {
+					recursive: true,
+					force: true
+				});
+			}
+		}
+	};
+}
+//#endregion
+//#region src/integrations/native-gradle-artifact-inputs.ts
+const NATIVE_GRADLE_CACHE_LIMIT = "Native APK caching requires android.artifactInputs with complete: true and a complete declaration of repeatable pinned inputs. Gradle incremental and task-cache reuse remain available without it.";
+function gradleArtifactInputs(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(NATIVE_GRADLE_CACHE_LIMIT);
+	const localFiles = "localFiles" in value ? value.localFiles : [];
+	const environment = "environment" in value ? value.environment : [];
+	if (Object.keys(value).some((key) => ![
+		"complete",
+		"ignored",
+		"outputs",
+		"localFiles",
+		"environment"
+	].includes(key)) || !Array.isArray(localFiles) || !localFiles.every((path) => typeof path === "string" && path.length > 0 && !path.includes("\0")) || !Array.isArray(environment) || !environment.every((name) => typeof name === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(name))) throw new Error(NATIVE_GRADLE_CACHE_LIMIT);
+	let inventory;
+	try {
+		inventory = gradleOffloadInputs({
+			complete: "complete" in value ? value.complete : void 0,
+			ignored: "ignored" in value ? value.ignored : void 0,
+			outputs: "outputs" in value ? value.outputs : void 0
+		});
+	} catch (error) {
+		throw new Error(String(error).replaceAll("android.offloadInputs", "android.artifactInputs"), { cause: error });
+	}
+	return {
+		...inventory,
+		localFiles: [...new Set(localFiles)].toSorted(),
+		environment: [...new Set(environment)].toSorted()
+	};
+}
+async function optionalText(path, signal, encoding = "utf8") {
+	try {
+		return await readFile(path, {
+			encoding,
+			signal
+		});
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return null;
+		throw error;
+	}
+}
+async function javaRelease(env, signal) {
+	let home = env.JAVA_HOME;
+	if (!home) {
+		const java = getExecutor().findExecutable("java");
+		if (java) {
+			const selected = dirname(dirname(await realpath(java)));
+			if ((await optionalText(join(selected, "release"), signal))?.includes("JAVA_VERSION=")) home = selected;
+		}
+	}
+	if (!home && process.platform === "darwin") {
+		const child = childEnvironment(env);
+		home = (await getExecutor().runFileAsync("/usr/libexec/java_home", [], {
+			timeoutMs: 1e4,
+			signal,
+			...child
+		})).trim();
+	}
+	if (!home || !(await optionalText(join(home, "release"), signal))?.includes("JAVA_VERSION=")) throw new Error("The Gradle wrapper JDK release identity is unavailable.");
+	return join(home, "release");
+}
+async function localPropertiesIdentity(properties, sdk, root, signal) {
+	const content = await optionalText(properties, signal, "latin1");
+	if (content === null) return null;
+	const retained = [];
+	let selected = null;
+	for (const [, line = "", ending = ""] of content.matchAll(/([^\r\n]*)(\r\n|\r|\n|$)/g)) {
+		if (/^[ \t\f]*$/.test(line) || /^[ \t\f]*[#!]/.test(line)) {
+			retained.push(line + ending);
+			continue;
+		}
+		if ((line.match(/\\+$/)?.[0].length ?? 0) % 2 !== 0) throw new Error("Native APK caching requires single-line local.properties values.");
+		const entry = /^[ \t\f]*([A-Za-z0-9_.-]+)(?:[ \t\f]*[:=][ \t\f]*|[ \t\f]+)(.*)$/.exec(line);
+		if (!entry) {
+			if (/^[ \t\f]*[A-Za-z0-9_.-]+[ \t\f]*$/.test(line) && line.trim() !== "sdk.dir") {
+				retained.push(line + ending);
+				continue;
+			}
+			throw new Error("Native APK caching requires plain, unescaped local.properties keys.");
+		}
+		if (entry[1] !== "sdk.dir") {
+			retained.push(line + ending);
+			continue;
+		}
+		const value = entry[2] ?? "";
+		if (!value || [...value].some((character) => character.charCodeAt(0) > 127)) throw new Error("Native APK caching cannot resolve the local.properties SDK.");
+		selected = value.replace(/\\u([a-fA-F\d]{4})|\\(.)/g, (full, hex, escaped) => {
+			if (hex) return String.fromCharCode(parseInt(hex, 16));
+			if (escaped === "u") throw new Error("Native APK caching cannot resolve the local.properties SDK.");
+			if (escaped === "t") return "	";
+			if (escaped === "r") return "\r";
+			if (escaped === "n") return "\n";
+			if (escaped === "f") return "\f";
+			return escaped ?? full;
+		});
+	}
+	if (selected !== null && await realpath(resolve(root, selected)) !== sdk) throw new Error("Native APK caching requires the local.properties SDK to match ANDROID_HOME.");
+	return retained.join("");
+}
+async function nativeGradleArtifactSnapshot(root, value, build, abi, env, signal) {
+	signal?.throwIfAborted();
+	const declaration = gradleArtifactInputs(value);
+	const localFiles = declaration.localFiles.map((file) => resolve(root, file));
+	for (const path of localFiles) {
+		const info = await stat(path).catch((error) => {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") return null;
+			throw error;
+		});
+		if (info && !info.isFile()) throw new Error("android.artifactInputs.localFiles must name exact regular files.");
+	}
+	const { complete, ignored, outputs } = declaration;
+	const properties = join(root, "local.properties");
+	const source = await nativeGradleLocalSourceDigest(root, {
+		complete,
+		ignored,
+		outputs
+	}, [properties, ...localFiles], signal);
+	const sdkDirectory = await realpath(androidHome(env));
+	const home = env.HOME ?? env.USERPROFILE ?? homedir();
+	const gradleHome = env.GRADLE_USER_HOME ?? join(home, ".gradle");
+	const inputs = [{
+		name: "jdk-release",
+		path: await javaRelease(env, signal),
+		optional: false
+	}, ...[
+		"gradle.properties",
+		"init.gradle",
+		"init.gradle.kts",
+		"init.d"
+	].map((name) => ({
+		name: `gradle-user/${name}`,
+		path: join(gradleHome, name),
+		optional: true
+	}))];
+	for (const group of [
+		"build-tools",
+		"platforms",
+		"ndk",
+		"cmake"
+	]) {
+		const directory = join(sdkDirectory, group);
+		const versions = await readdir(directory).catch((error) => {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") return [];
+			throw error;
+		});
+		for (const version of versions.toSorted()) {
+			if (!(await stat(join(directory, version))).isDirectory()) continue;
+			const path = join(directory, version, "source.properties");
+			if (await optionalText(path, signal) !== null) inputs.push({
+				name: `sdk/${group}/${version}`,
+				path,
+				optional: false
+			});
+		}
+	}
+	if (!inputs.some((input) => input.name.startsWith("sdk/build-tools/"))) throw new Error("Android SDK build-tools version metadata is unavailable.");
+	const preferences = [
+		join(home, ".android"),
+		...env.ANDROID_USER_HOME ? [env.ANDROID_USER_HOME] : [],
+		...[
+			"ANDROID_PREFS_ROOT",
+			"ANDROID_SDK_HOME",
+			"TEST_TMPDIR"
+		].flatMap((name) => env[name] ? [join(env[name], ".android")] : [])
+	];
+	for (const [index, directory] of [...new Set(preferences)].entries()) inputs.push({
+		name: `debug-keystore/${index}`,
+		path: join(directory, "debug.keystore"),
+		optional: true
+	});
+	for (const [index, path] of localFiles.entries()) inputs.push({
+		name: `local/${index}`,
+		path,
+		optional: true
+	});
+	const environment = Object.fromEntries([.../* @__PURE__ */ new Set([
+		...declaration.environment,
+		"JAVA_OPTS",
+		"JAVA_TOOL_OPTIONS",
+		"_JAVA_OPTIONS",
+		"GRADLE_OPTS"
+	])].toSorted().map((name) => [name, env[name] ?? null]));
+	const localProperties = await localPropertiesIdentity(properties, sdkDirectory, root, signal);
+	const local = await fingerprintNativeInputs(inputs, {
+		parameters: {
+			declaration,
+			environment,
+			localProperties: createHash("sha256").update(JSON.stringify(localProperties)).digest("hex")
+		},
+		signal
+	});
+	const hash = createHash("sha256").update("stim-native-gradle-artifact-v1\0").update(JSON.stringify({
+		source,
+		local: local.hash,
+		platform: process.platform,
+		arch: process.arch,
+		variant: build.variant ?? "debug",
+		compilerCache: build.compilerCache,
+		gradleBuildCache: build.gradleBuildCache,
+		pch: build.pch,
+		cas: build.cas,
+		abi
+	})).digest("hex");
+	return {
+		hash,
+		key: buildCacheKey("android", hash, {
+			variant: build.variant ?? "debug",
+			...abi ? { abi } : {}
+		}),
+		sdkDirectory
+	};
+}
+//#endregion
+//#region src/integrations/native-android-plan.ts
+async function planNativeAndroid(root, options, resolved, operation) {
+	if (options.easProfile !== void 0) return { refusal: planFlagRefusal("--eas-profile") };
+	try {
+		const slot = validateDeviceSlot(options.slot);
+		const { context, settings } = resolved;
+		const { env, signal } = operation;
+		const declared = settingValueAt(settings, "android.artifactInputs");
+		gradleArtifactInputs(declared);
+		const planned = resolveAndroidRunPlan({
+			settings,
+			settingsContext: context,
+			env,
+			slot,
+			variant: options.variant ?? null,
+			systemImage: options.systemImage ?? null,
+			deviceProfile: options.deviceProfile ?? null,
+			device: null,
+			wait: void 0,
+			waitConflict: false,
+			remote: null,
+			buildCache: options.buildCache !== false
+		}, {
+			runtimeKind: () => "process",
+			variantProblem: () => null,
+			resolveCompilerCache: ({ optimizations }) => {
+				if (optimizations.android.compilerCache === "cas") throw new Error("Native Android planning does not initialize the experimental CAS toolchain.");
+				return {
+					cas: null,
+					optimizations,
+					warning: null
+				};
+			},
+			warn: (label, message) => operation.output("stderr", `${label}: ${message}\n`)
+		});
+		if (!planned.ok) return { refusal: planned };
+		const { build, target } = planned.plan;
+		if (target.kind !== "emulator") throw new Error("Native Android planning requires a local emulator target.");
+		const recorded = deviceSlotPlatforms(getProject(root), slot)?.android;
+		let reuseRecorded = Boolean(recorded?.owned && recorded.avdName && !recorded.setupIncomplete && ownedAvdDirectory(recorded.avdName));
+		const recordedImage = reuseRecorded && recorded?.avdName ? ownedAvdSystemImage(recorded.avdName) : null;
+		const requestedImage = options.systemImage?.trim();
+		if (recordedImage && requestedImage && recordedImage !== requestedImage) {
+			if (!recorded?.bootPending) return { refusal: {
+				code: "STIM_BAD_ARG",
+				message: `The recorded emulator uses ${recordedImage}; --system-image ${requestedImage} only replaces an emulator that never finished booting.`,
+				remedy: "Use the existing image or pass --slot <name> to create the requested emulator beside it."
+			} };
+			reuseRecorded = false;
+		}
+		if (reuseRecorded && recorded?.avdName && target.deviceProfile) {
+			const recordedProfile = ownedAvdDeviceProfile(recorded.avdName);
+			if (recordedProfile && recordedProfile !== target.deviceProfile) return { refusal: {
+				code: "STIM_BAD_ARG",
+				message: `The recorded emulator uses device profile ${recordedProfile}, but ${target.deviceProfile} was requested.`,
+				remedy: "Use the existing profile or pass --slot <name> to create the requested emulator beside it."
+			} };
+		}
+		let abi = null;
+		if (build.targetAbiOnly && !build.release) {
+			if (recorded?.avdName && !recorded.owned) return { refusal: {
+				code: "STIM_BAD_ARG",
+				message: "The legacy emulator assignment does not establish a build ABI for native planning.",
+				remedy: "Run stim android without --plan to reconcile the assignment, or use --slot <name> for an owned emulator."
+			} };
+			const image = reuseRecorded ? recordedImage : pickDefaultSystemImage(listInstalledSystemImages(), target.systemImage ? { systemImage: target.systemImage } : {})?.pkg;
+			abi = androidSystemImageAbi(image);
+			if (!abi) throw new Error("No installed emulator image identifies the native Android build ABI.");
+		}
+		const snapshot = await nativeGradleArtifactSnapshot(root, declared, build, abi, env, signal);
+		const hit = build.cache.read && await plannedNativeApk(snapshot.key, snapshot.sdkDirectory, abi, operation);
+		return planPayload({
+			root,
+			platform: "android",
+			slot,
+			projectKey: statsProjectKey({
+				root,
+				commonDir: context.gitCommonDir,
+				repoRoot: context.repoRoot
+			})
+		}, {
+			fingerprint: snapshot.hash,
+			cacheKey: snapshot.key,
+			cacheHit: hit ? "local" : false,
+			cacheSkipped: !build.cache.read,
+			provider: null,
+			prebuild: null,
+			refusal: null
+		});
+	} catch (error) {
+		operation.signal.throwIfAborted();
+		return { refusal: {
+			code: "STIM_BAD_ARG",
+			message: error.message,
+			remedy: "Check android.artifactInputs and the local Android toolchain, or run stim android without --plan for an uncached build."
+		} };
+	}
+}
+//#endregion
+//#region src/integrations/native-android.ts
+const CACHE_LIMIT = `${NATIVE_GRADLE_CACHE_LIMIT} Offload requires a separate complete android.offloadInputs declaration and remains uncached.`;
+const MODEL_LIMIT = "Native Android requires AGP with androidComponents, one application module and configuration-on-demand disabled. Gradle resolves the exact variant and APK outputs during the build.";
+function refusal(reason) {
+	return {
+		code: "STIM_BUILD_FAILED",
+		reason,
+		remedy: "Select one signed standalone APK for the requested variant and target ABI in the Android application module, then retry. Stim does not sign APKs or install split APK sets."
+	};
+}
+function selectNativeApk(value, variant, abi) {
+	const model = value;
+	if (!model || model.schema !== 1 || typeof model.module !== "string" || !model.module.startsWith(":") || model.variant !== variant || typeof model.applicationId !== "string" || !/^[A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)+$/.test(model.applicationId) || typeof model.sdkDirectory !== "string" || !isAbsolute(model.sdkDirectory) || !Array.isArray(model.elements) || !model.elements.every((element) => element && typeof element.path === "string" && isAbsolute(element.path) && element.path.endsWith(".apk") && Array.isArray(element.filters) && element.filters.every((filter) => filter && typeof filter.type === "string" && typeof filter.value === "string"))) return refusal("Gradle did not export a valid model for the requested native Android variant.");
+	const universal = model.elements.filter((element) => element.filters.length === 0);
+	const candidates = universal.length ? universal : model.elements.filter((element) => abi !== null && element.filters.length === 1 && element.filters[0].type === "ABI" && element.filters[0].value === abi);
+	if (candidates.length !== 1) return refusal(`Native variant "${variant}" has ${candidates.length} installable APK candidates for ${abi ?? "an unspecified ABI"}. Density splits and ambiguous output sets are unsupported.`);
+	return {
+		apkPath: candidates[0].path,
+		androidPackage: model.applicationId
+	};
+}
+async function locateNativeApk(modelFile, variant, abi) {
+	let value;
+	try {
+		value = JSON.parse(readFileSync(modelFile, "utf8"));
+	} catch {
+		return refusal("Gradle succeeded without exporting the native Android APK model.");
+	}
+	const located = selectNativeApk(value, variant, abi);
+	if ("code" in located) return located;
+	try {
+		if (!statSync(located.apkPath).isFile()) return refusal("The APK selected by Gradle is not a file.");
+	} catch {
+		return refusal("The APK selected by Gradle does not exist.");
+	}
+	const signer = findBuildTool(["apksigner"], { home: value.sdkDirectory });
+	if (!signer) return refusal("No Android SDK apksigner is available to verify the native APK signature.");
+	try {
+		await getExecutor().runFileAsync(signer.path, ["verify", located.apkPath], { timeoutMs: 3e4 });
+	} catch (error) {
+		return refusal(`The native APK signature could not be verified: ${error.message}`);
+	}
+	return located;
+}
+function nativeAndroidProject(root) {
+	return {
+		isExpo: false,
+		packageRemedy: "Check the applicationId reported by AGP for the selected application variant.",
+		appIds: () => ({
+			bundleId: null,
+			androidPackage: null
+		}),
+		variantProblem: () => null,
+		targets: [
+			"emulator",
+			"physical",
+			"hosted"
+		],
+		eas: false,
+		runtimeKind: () => "process",
+		plan: (options, resolved, operation) => planNativeAndroid(root, options, resolved, operation),
+		runtime: ({ phase }) => androidProcessRuntime(async () => {
+			phase("metro", "skipped (native process)");
+			return {
+				ok: true,
+				prepared: { metroPort: null }
+			};
+		}),
+		artifact: ({ operation, cacheArtifacts, writer, buildPlan, target, out, estimates, settings }) => {
+			const variant = buildPlan.variant ?? "debug";
+			const inputs = settingValueAt(settings, "android.offloadInputs");
+			const artifactInputs = settingValueAt(settings, "android.artifactInputs");
+			let snapshot = null;
+			let cacheRefusal = CACHE_LIMIT;
+			let compiledPackage = null;
+			let compiledSdk = null;
+			const signal = runCancellationSignal(operation) ?? operation?.signal;
+			const read = () => {
+				if (!operation) throw new Error("Native APK caching requires an operation context.");
+				return nativeGradleArtifactSnapshot(root, artifactInputs, buildPlan, target.abi, operation.env, signal);
+			};
+			let transfer = null;
+			const modelFile = join(workspaceDir(root), "gradle-build", `native-apk-${encodeURIComponent(variant)}.json`);
+			return {
+				providerCache: (provider) => {
+					if (!provider.files) return void 0;
+					if (!snapshot) throw new Error(CACHE_LIMIT);
+					return nativeAndroidFileCache(provider.files, snapshot.sdkDirectory, target.abi, operation);
+				},
+				identity: async () => {
+					if (cacheArtifacts === false) return { cacheIneligible: "Native Gradle worker artifacts have no reusable APK identity." };
+					try {
+						snapshot = await read();
+						cacheRefusal = null;
+						return snapshot;
+					} catch (error) {
+						signal?.throwIfAborted();
+						cacheRefusal = error instanceof Error ? error.message : String(error);
+						return { cacheIneligible: cacheRefusal };
+					}
+				},
+				cache: () => {
+					if (!snapshot) throw new Error(CACHE_LIMIT);
+					return nativeAndroidCache(snapshot.sdkDirectory, target.abi, () => compiledPackage, operation);
+				},
+				prepare: async () => {},
+				reconcile: async () => {
+					if (snapshot) try {
+						snapshot = await read();
+					} catch {
+						signal?.throwIfAborted();
+						snapshot = null;
+					}
+					return {
+						identity: snapshot,
+						rekeyedBy: [],
+						cacheRefusal: null
+					};
+				},
+				validate: async () => {
+					if (!snapshot || compiledSdk !== snapshot.sdkDirectory) return null;
+					try {
+						return (await read()).hash === snapshot.hash ? snapshot : null;
+					} catch {
+						signal?.throwIfAborted();
+						return null;
+					}
+				},
+				materialize: async (key, path) => {
+					if (!snapshot) return null;
+					try {
+						if ((await read()).hash !== snapshot.hash) return null;
+						return await materializeNativeApk(key, path, snapshot.sdkDirectory, target.abi, operation);
+					} catch {
+						signal?.throwIfAborted();
+						return null;
+					}
+				},
+				explain: (rekeyedBy) => ({
+					reason: snapshot ? explainBuildMiss({
+						root,
+						platform: "android",
+						current: {
+							hash: snapshot.hash,
+							sources: []
+						},
+						rekeyedBy
+					}).reason : skippedMissReason(cacheRefusal ?? CACHE_LIMIT),
+					diff: null
+				}),
+				untrackedLine: () => null,
+				legacyCache: null,
+				offload: {
+					supportsUncachedArtifacts: true,
+					uncachedArtifacts: true,
+					get unsupported() {
+						if (buildPlan.cas) return "Apple Clang CAS builds build here";
+						try {
+							gradleOffloadInputs(inputs);
+							return null;
+						} catch (error) {
+							return error.message;
+						}
+					},
+					target: async () => {
+						transfer = await nativeGradleTransfer(root, inputs, runCancellationSignal(operation) ?? operation?.signal);
+						return {
+							platform: "android",
+							native: "gradle",
+							local: await androidToolchainAsync(operation?.env),
+							requires: {
+								ndk: null,
+								buildTools: null,
+								compileSdk: null
+							}
+						};
+					},
+					get request() {
+						if (!transfer) throw new Error("Native Gradle offload needs a declared source inventory.");
+						return {
+							platform: "android",
+							isExpo: false,
+							native: {
+								provider: "gradle",
+								transfer
+							},
+							android: {
+								variant,
+								abi: target.abi,
+								gradleBuildCache: buildPlan.gradleBuildCache,
+								pch: buildPlan.pch,
+								compilerCache: buildPlan.compilerCache === "none" ? "none" : "ccache"
+							}
+						};
+					},
+					unchanged: async () => transfer !== null && (await nativeGradleTransfer(root, inputs, runCancellationSignal(operation) ?? operation?.signal)).digest === transfer.digest
+				},
+				compile: async () => {
+					const script = ["../shim/native-android.gradle", "../../shim/native-android.gradle"].map((path) => fileURLToPath(new URL(path, import.meta.url))).find(existsSync);
+					if (!script) throw new Error("Stim installation is missing shim/native-android.gradle.");
+					return await buildGradle({
+						root,
+						logWriter: writer,
+						variant,
+						project: {
+							directory: root,
+							gradlew: join(root, process.platform === "win32" ? "gradlew.bat" : "gradlew"),
+							module: ":",
+							outputsDir: root
+						},
+						task: ":stimExportAndroidApk",
+						projectArgs: [
+							"--init-script",
+							script,
+							`-Pstim.native.variant=${variant}`,
+							`-Pstim.native.model=${modelFile}`
+						],
+						locate: async () => {
+							const located = await locateNativeApk(modelFile, variant, target.abi);
+							if (!("code" in located)) {
+								compiledSdk = await realpath(JSON.parse(readFileSync(modelFile, "utf8")).sdkDirectory);
+								compiledPackage = located.androidPackage ?? null;
+							}
+							return located;
+						}
+					}, {
+						estimateMs: estimates().coldBuildMs,
+						onHeartbeat: out,
+						onNote: out,
+						ccache: buildPlan.compilerCache === "ccache" ? resolveCcache({
+							root,
+							onNote: out,
+							env: operation?.env
+						}) : null,
+						cas: buildPlan.cas,
+						buildCache: buildPlan.gradleBuildCache,
+						pch: buildPlan.pch,
+						compilerCacheDisabled: buildPlan.compilerCache === "none"
+					});
+				}
+			};
+		}
+	};
+}
+function nativeAndroidDoctor(root) {
+	return { inspect: ({ settings }) => {
+		let cache = CACHE_LIMIT;
+		try {
+			gradleArtifactInputs(settingValueAt(settings, "android.artifactInputs"));
+			cache = "Local native APK caching uses the project-declared complete inputs. Build workers remain uncached and need their separate android.offloadInputs declaration.";
+		} catch {}
+		const sdkPath = androidHome();
+		const sdk = androidSdkRefusal({
+			sdkPath,
+			sdkExists: existsSync(sdkPath),
+			hasLocalProperties: existsSync(join(root, "local.properties")),
+			localPropertiesPath: "local.properties"
+		});
+		const wrapper = join(root, process.platform === "win32" ? "gradlew.bat" : "gradlew");
+		return [
+			{
+				level: "note",
+				title: "Native Android Gradle project",
+				detail: `${MODEL_LIMIT} ${cache} Metro and EAS are unsupported; local, physical and hosted targets use native process readiness.`,
+				fix: null
+			},
+			...sdk ? [{
+				level: "cost",
+				code: "android-sdk-missing",
+				title: "No Android SDK was found",
+				detail: sdk.reason,
+				fix: sdk.remedy
+			}] : [],
+			...!existsSync(wrapper) ? [{
+				level: "cost",
+				code: "android-wrapper-missing",
+				title: "The Gradle wrapper for this host is missing",
+				detail: wrapper,
+				fix: "Restore the project Gradle wrapper."
+			}] : []
+		];
+	} };
+}
+//#endregion
+export { nativeAndroidDoctor, nativeAndroidProject };