kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/android/stage/__init__.py

@@ -0,0 +1 @@
+"""Stage-step helpers: runtime extract, per-ABI wheel install, jniLibs, bundle."""

kivyforge/platforms/android/stage/bundle.py

@@ -0,0 +1,295 @@
+"""Assemble the ABI-independent Python asset bundle (android/04 §asset bundle).
+
+Layout under ``app/src/main/assets/_python_bundle/``:
+
+- ``stdlib/``        — the runtime's pure-Python stdlib (no ``lib-dynload``,
+  no ``__pycache__``, no ``*.gz`` — AGP auto-decompresses ``.gz`` assets,
+  loadmodel findings §corrections #5; ``test``/``idlelib``/``turtledemo``
+  excluded for size, matching the proven prototype).
+- ``site-packages/`` — pure-Python content of the installed wheels (``.so``s
+  and ``.libs/`` were hoisted into ``jniLibs``).
+- ``app/``           — the user's ``app_dir`` payload.
+- ``bootstrap/``     — the finder module, Kivy's ``_kivy_bootstrap`` contract
+  module, and ``ext_manifest.json``.
+- ``VERSION``        — content stamp; a changed bundle re-extracts on-device.
+
+``byte_compile``/``strip_source`` (android/01 §build_settings) act on the
+assembled tree just before the stamp is taken, so the stamp always describes
+what actually ships.
+
+**ABI-independent by construction, and verified so**: the bundle is assembled
+from the canonical ABI (first in ``abis``); every other ABI's non-``.so``
+site-packages payload must be byte-for-byte identical or the build fails
+naming the path and both hashes (version skew is already rejected at lock
+time; this catches content skew).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import shutil
+from pathlib import Path
+
+from kivyforge.artifacts.verify import sha256_file
+
+# Imported as a module, not by name: ``assemble_bundle`` takes a *parameter*
+# called ``byte_compile`` (the compiler argv), so a bare import would shadow.
+from kivyforge.bundle import pycompile
+
+BUNDLE_DIRNAME = "_python_bundle"
+
+_STDLIB_EXCLUDED_DIRS = {
+    "__pycache__",
+    "lib-dynload",
+    "site-packages",
+    "test",
+    "idlelib",
+    "turtledemo",
+}
+
+
+class BundleError(Exception):
+    pass
+
+
+def assemble_bundle(
+    bundle_dir: Path,
+    *,
+    stdlib_src: Path,
+    site_packages_by_abi: dict[str, Path],
+    canonical_abi: str,
+    app_src: Path,
+    finder_source: str,
+    kivy_bootstrap_source: str,
+    ext_manifest_json: str,
+    selftest_source: str = "",
+    entry_point: str = "main",
+    service_entry_points: dict[str, str] | None = None,
+    byte_compile: tuple[str, ...] | None = None,
+    strip_source: bool = False,
+) -> str:
+    """Assemble the bundle; returns the content stamp written to ``VERSION``."""
+    if bundle_dir.exists():
+        shutil.rmtree(bundle_dir)
+    bundle_dir.mkdir(parents=True)
+
+    _copy_stdlib(stdlib_src, bundle_dir / "stdlib")
+    canonical_sp = site_packages_by_abi[canonical_abi]
+    _copy_pure(canonical_sp, bundle_dir / "site-packages")
+    _assert_abi_identity(site_packages_by_abi, canonical_abi)
+    _copy_app(
+        app_src,
+        bundle_dir / "app",
+        entry_point=entry_point,
+        service_entry_points=service_entry_points or {},
+    )
+
+    bootstrap = bundle_dir / "bootstrap"
+    bootstrap.mkdir()
+    (bootstrap / "_kivyforge_bootstrap.py").write_text(finder_source, encoding="utf-8")
+    # Required, not optional: Kivy resolves the Activity by importing this
+    # module, so an app built without it would start and then fail the moment
+    # Kivy needed the Activity.
+    (bootstrap / "_kivy_bootstrap.py").write_text(
+        kivy_bootstrap_source, encoding="utf-8"
+    )
+    if selftest_source:
+        (bootstrap / "_kivyforge_selftest.py").write_text(
+            selftest_source, encoding="utf-8"
+        )
+    (bootstrap / "ext_manifest.json").write_text(ext_manifest_json, encoding="utf-8")
+
+    if byte_compile is not None:
+        _byte_compile(bundle_dir, compiler=byte_compile, strip_source=strip_source)
+
+    stamp = _content_stamp(bundle_dir)
+    (bundle_dir / "VERSION").write_text(stamp, encoding="utf-8")
+    return stamp
+
+
+def _byte_compile(
+    bundle_dir: Path, *, compiler: tuple[str, ...], strip_source: bool
+) -> None:
+    """Compile the bundle's Python payload to ``.pyc`` in place (android/01).
+
+    The mechanics live in :mod:`kivyforge.bundle.pycompile` (shared with the
+    desktop backends); this only names the payload areas and translates the
+    failure into a ``BundleError`` carrying the Android config key.
+
+    Android compiles **all four** areas, stdlib included — unlike desktop,
+    which leaves the stdlib alone. The payload is unpacked to app-private
+    storage on first launch, so stripping stdlib source is what keeps the APK
+    (and that unpack) small.
+
+    Paths are stripped to be bundle-relative for the same reason ``_copy_pure``
+    drops ``direct_url.json``: a ``.pyc`` records the path it was compiled from,
+    so the default would both leak local host paths into the shipped APK and
+    make the content stamp differ per machine.
+    """
+    trees = [
+        bundle_dir / name for name in ("stdlib", "site-packages", "app", "bootstrap")
+    ]
+    try:
+        pycompile.byte_compile(
+            trees,
+            compiler=compiler,
+            strip_source=strip_source,
+            stripdir=bundle_dir,
+        )
+    except pycompile.PycompileError as exc:
+        raise BundleError(
+            f"{exc}\n"
+            "  Fix it, or set [tool.kivy.android.build_settings].byte_compile "
+            "= false."
+        ) from exc
+
+
+def _copy_stdlib(src: Path, dest: Path) -> None:
+    def ignore(directory: str, names: list[str]) -> list[str]:
+        return [n for n in names if n in _STDLIB_EXCLUDED_DIRS or n.endswith(".gz")]
+
+    shutil.copytree(src, dest, ignore=ignore)
+
+
+def _copy_pure(src: Path, dest: Path) -> None:
+    """Copy an installed site-packages tree minus native payload.
+
+    ``dist-info/direct_url.json`` is dropped entirely: pip writes the install
+    source into it (a per-ABI ``file:///`` URL for vendored wheels), which
+    both breaks ABI identity by design and would leak local host paths into
+    the shipped APK.
+
+    ``bin/`` — pip's console-script launchers — is dropped for the same class
+    of reason, and it is worth being explicit because the symptom is
+    confusing. Nothing on Android can invoke a console script, and pip
+    generates the launchers for the *host*: installing from Windows yields
+    Windows ``.exe`` wrappers (``filetype.exe``, ``idna.exe``, …) inside an
+    Android APK. They also embed the per-ABI target path, so they differ
+    between slices and trip the ABI-identity assertion — which is how this was
+    found: ``kivyforge build -p android`` across both ABIs failed with
+    "ABI content skew in the pure-Python payload: 'bin/filetype.exe'".
+    """
+
+    def ignore(directory: str, names: list[str]) -> list[str]:
+        out = [n for n in names if n == "__pycache__" or n.endswith(".so")]
+        if Path(directory).name.endswith(".dist-info"):
+            out += [n for n in names if n == "direct_url.json"]
+        if Path(directory).resolve() == src.resolve():
+            # top-level flat .libs/ was hoisted into jniLibs
+            out += [n for n in names if n == ".libs"]
+            # host-generated console scripts; see the docstring
+            out += [n for n in names if n == "bin"]
+        return out
+
+    if src.exists():
+        shutil.copytree(src, dest, ignore=ignore)
+    else:
+        dest.mkdir(parents=True)
+
+
+def _require_module(src: Path, entry_point: str, hint: str) -> None:
+    """A dotted entry point must resolve to a module or package in ``app_dir``.
+
+    ``pkg.start`` maps to a nested module; a package entry point is imported
+    through its ``__init__.py``. Catching an unresolvable one here beats a black
+    screen and an ImportError in logcat.
+    """
+    rel = "/".join(entry_point.split("."))
+    if not (src / f"{rel}.py").is_file() and not (src / rel / "__init__.py").is_file():
+        raise BundleError(f"entry point {rel}.py not found in {src.name}/ ({hint}).")
+
+
+def _copy_app(
+    src: Path,
+    dest: Path,
+    *,
+    entry_point: str = "main",
+    service_entry_points: dict[str, str],
+) -> None:
+    if not src.is_dir():
+        raise BundleError(
+            f"[tool.kivy].app_dir does not exist or is not a directory: {src}"
+        )
+    _require_module(src, entry_point, "set [tool.kivy].entry_point")
+    # A service whose entry point does not exist starts, comes up, and then dies
+    # on the import in a separate process — where nothing is watching.
+    for name, service_entry in sorted(service_entry_points.items()):
+        _require_module(
+            src,
+            service_entry,
+            f"set entry_point for [[tool.kivy.android.services]] {name!r}",
+        )
+
+    def ignore(directory: str, names: list[str]) -> list[str]:
+        return [n for n in names if n == "__pycache__"]
+
+    shutil.copytree(src, dest, ignore=ignore)
+
+
+def _assert_abi_identity(
+    site_packages_by_abi: dict[str, Path], canonical_abi: str
+) -> None:
+    """Every ABI's non-``.so`` payload must match the canonical ABI's exactly."""
+    canonical = _pure_hashes(site_packages_by_abi[canonical_abi])
+    for abi, sp in site_packages_by_abi.items():
+        if abi == canonical_abi:
+            continue
+        other = _pure_hashes(sp)
+        if other == canonical:
+            continue
+        for rel in sorted(set(canonical) | set(other)):
+            a, b = canonical.get(rel), other.get(rel)
+            if a != b:
+                raise BundleError(
+                    f"ABI content skew in the pure-Python payload: {rel!r} is "
+                    f"{'missing' if a is None else a[:12] + '…'} for "
+                    f"{canonical_abi} but "
+                    f"{'missing' if b is None else b[:12] + '…'} for {abi}.\n"
+                    f"  An ABI slice shipping different Python source/data at "
+                    f"the same version cannot back a single shared bundle "
+                    f"(android/04 §asset bundle)."
+                )
+        raise BundleError(  # pragma: no cover - loop above always raises
+            f"ABI content skew between {canonical_abi} and {abi}"
+        )
+
+
+def _pure_hashes(root: Path) -> dict[str, str]:
+    out: dict[str, str] = {}
+    if not root.exists():
+        return out
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(root)
+        parts = rel.parts
+        # Mirrors _copy_pure's exclusions: anything not shipped must not be
+        # compared either, or the assertion fails on files the bundle drops.
+        if "__pycache__" in parts or parts[0] in (".libs", "bin"):
+            continue
+        if path.suffix == ".so":
+            continue
+        # dist-info RECORD/WHEEL are per-ABI BY DESIGN (they list the wheel's
+        # own files/tags, which include the ABI-specific .so names), so they
+        # are exempt from the identity assertion; the canonical ABI's copies
+        # ship in the bundle. Everything else in dist-info stays checked.
+        if (
+            len(parts) >= 2
+            and parts[-2].endswith(".dist-info")
+            and parts[-1] in ("RECORD", "WHEEL", "direct_url.json")
+        ):
+            continue
+        out[rel.as_posix()] = sha256_file(path)
+    return out
+
+
+def _content_stamp(bundle_dir: Path) -> str:
+    """A deterministic stamp over every (relpath, sha256) pair in the bundle."""
+    digest = hashlib.sha256()
+    for path in sorted(bundle_dir.rglob("*")):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(bundle_dir).as_posix()
+        digest.update(rel.encode("utf-8"))
+        digest.update(sha256_file(path).encode("ascii"))
+    return digest.hexdigest()[:16]

kivyforge/platforms/android/stage/jnilibs.py

@@ -0,0 +1,186 @@
+"""Populate ``jniLibs/<abi>/`` (android/04 §"Native libraries and the .so load model").
+
+Two kinds of ``.so``, found two different ways at runtime:
+
+- **Shared libraries** resolved by soname (``System.loadLibrary`` /
+  ``DT_NEEDED``): ``libpython3.X.so``, the runtime's ``lib*_python.so``, the
+  SDL family from a wheel's ``.libs/``. Copied verbatim, names unchanged.
+- **Extension modules** imported by dotted name: flattened to
+  ``libpy.<dotted>.so`` (the platform's native-lib extraction requires the
+  ``lib*.so`` shape — proven on-device, loadmodel findings §confirmed #1) and
+  recorded in the ``ext_manifest.json`` the bootstrap finder consumes.
+
+Wheel ``.libs/`` is **flat-only**: a nested subdirectory is a malformed wheel
+and fails the build (android/03/04 — the wheel tag is the sole ABI truth).
+The duplicate policy is the iOS rule adapted: identical content dedupes
+silently; same basename with different bytes aborts naming both providers.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from kivyforge.artifacts.verify import sha256_file
+
+EXT_MANIFEST_NAME = "ext_manifest.json"
+
+# Suffix pattern of CPython extension modules: everything from the first "."
+# after the module path is the ABI suffix (".cpython-314-....so" or just ".so").
+_SO_SUFFIX = ".so"
+
+
+class JniLibsError(Exception):
+    pass
+
+
+@dataclass
+class JniLibsStager:
+    """Accumulates ``.so`` files for one ABI, enforcing the duplicate policy.
+
+    ``provider`` strings name where a file came from (e.g. ``"runtime"``,
+    ``"wheel kivy"``) so a conflict diagnostic can name both sides.
+    """
+
+    dest: Path
+    # basename -> (sha256, provider)
+    _seen: dict[str, tuple[str, str]] = field(default_factory=dict)
+    # dotted module -> flattened filename
+    _manifest: dict[str, str] = field(default_factory=dict)
+
+    def add_shared_library(self, source: Path, *, provider: str) -> None:
+        """Copy a soname-resolved library verbatim (name unchanged)."""
+        self._add(source, source.name, provider=provider)
+
+    def add_extension_module(self, source: Path, *, dotted: str, provider: str) -> None:
+        """Flatten one extension module and record it in the finder manifest."""
+        flattened = f"libpy.{dotted}.so"
+        existing = self._manifest.get(dotted)
+        if existing is not None and existing != flattened:
+            raise JniLibsError(
+                f"extension module {dotted!r} maps to both {existing!r} and "
+                f"{flattened!r}"
+            )
+        self._add(source, flattened, provider=provider)
+        self._manifest[dotted] = flattened
+
+    def manifest(self) -> dict[str, str]:
+        return dict(sorted(self._manifest.items()))
+
+    def write_manifest(self, bootstrap_dir: Path) -> Path:
+        bootstrap_dir.mkdir(parents=True, exist_ok=True)
+        out = bootstrap_dir / EXT_MANIFEST_NAME
+        out.write_text(
+            json.dumps(self.manifest(), indent=1, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+        return out
+
+    def _add(self, source: Path, basename: str, *, provider: str) -> None:
+        digest = sha256_file(source)
+        prior = self._seen.get(basename)
+        if prior is not None:
+            prior_sha, prior_provider = prior
+            if prior_sha == digest:
+                return  # identical -> silent dedupe
+            raise JniLibsError(
+                f"conflicting native library {basename!r} for {self.dest.name}: "
+                f"{prior_provider} and {provider} supply different contents "
+                f"(sha256 {prior_sha[:12]}… vs {digest[:12]}…).\n"
+                f"  kivyforge never picks a winner — a version-mismatched .so "
+                f"can link and then crash at runtime (android/04 §duplicate "
+                f".so policy)."
+            )
+        self.dest.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, self.dest / basename)
+        self._seen[basename] = (digest, provider)
+
+
+def dotted_module_name(so_path: Path, site_packages_root: Path) -> str:
+    """``site-packages/jnius/jnius.cpython-314-….so`` -> ``jnius.jnius``."""
+    rel = so_path.relative_to(site_packages_root)
+    stem = rel.name.split(".", 1)[0]
+    parts = [*rel.parts[:-1], stem]
+    return ".".join(parts)
+
+
+def stage_wheel_libs_dir(
+    stager: JniLibsStager, libs_dir: Path, *, wheel_name: str
+) -> int:
+    """Ingest one wheel's flat ``.libs/`` (SDL family etc.). Returns the count.
+
+    Flat-only: any subdirectory is a malformed wheel (android/03). The ABI is
+    the wheel tag's business — the caller already routed this stager to the
+    right ABI.
+    """
+    count = 0
+    for entry in sorted(libs_dir.iterdir()):
+        if entry.is_dir():
+            raise JniLibsError(
+                f"wheel {wheel_name!r} has a nested .libs/ subdirectory "
+                f"({entry.name!r}); .libs/ must be flat — the wheel platform "
+                f"tag is the sole source of truth for the ABI (android/03 "
+                f"§flat only)."
+            )
+        if entry.suffix == _SO_SUFFIX:
+            stager.add_shared_library(entry, provider=f"wheel {wheel_name}")
+            count += 1
+    return count
+
+
+def stage_site_packages_extensions(
+    stager: JniLibsStager, site_packages: Path, *, wheel_name: str
+) -> int:
+    """Flatten every extension ``.so`` under an installed wheel's tree."""
+    count = 0
+    for so in sorted(site_packages.rglob(f"*{_SO_SUFFIX}")):
+        if ".libs" in so.relative_to(site_packages).parts[:1]:
+            continue  # the flat .libs/ dir is handled by stage_wheel_libs_dir
+        stager.add_extension_module(
+            so,
+            dotted=dotted_module_name(so, site_packages),
+            provider=f"wheel {wheel_name}",
+        )
+        count += 1
+    return count
+
+
+def stage_runtime_libs(
+    stager: JniLibsStager, prefix_lib: Path, *, python_stem: str
+) -> tuple[int, int]:
+    """Stage the extracted runtime's ``prefix/lib`` for one ABI.
+
+    Returns ``(shared_count, extension_count)``. Follows the python.org
+    app-integration split, extended for multi-ABI (android/03 channel 2):
+
+    - ``lib<python_stem>.so`` + ``lib*_python.so`` -> verbatim (soname libs).
+      The runtime's plain ``lib{ssl,crypto,sqlite3}.so`` / ``engines-3`` /
+      ``ossl-modules`` are NOT shipped — the ``_python``-soname copies are the
+      ones the extensions link against (proven on-device; loadmodel findings
+      §runtime-package facts).
+    - ``lib/<python_stem>/lib-dynload/*.so`` -> flattened extension modules
+      (all top-level stdlib names).
+    """
+    shared = 0
+    libpython = prefix_lib / f"lib{python_stem}.so"
+    if not libpython.is_file():
+        raise JniLibsError(
+            f"runtime prefix has no lib{python_stem}.so under {prefix_lib}"
+        )
+    stager.add_shared_library(libpython, provider="runtime")
+    shared += 1
+    for candidate in sorted(prefix_lib.glob("lib*_python.so")):
+        stager.add_shared_library(candidate, provider="runtime")
+        shared += 1
+
+    extensions = 0
+    dynload = prefix_lib / python_stem / "lib-dynload"
+    if not dynload.is_dir():
+        raise JniLibsError(f"runtime prefix has no lib-dynload directory at {dynload}")
+    for so in sorted(dynload.glob(f"*{_SO_SUFFIX}")):
+        dotted = so.name.split(".", 1)[0]
+        stager.add_extension_module(so, dotted=dotted, provider="runtime")
+        extensions += 1
+    return shared, extensions

kivyforge/platforms/android/stage/runtime.py

@@ -0,0 +1,61 @@
+"""Extract the python.org Android runtime per ABI (android/03 channel 2).
+
+The tarball layout (loadmodel findings §runtime-package facts):
+``README.md``, ``android-env.sh``, ``android.py``, ``prefix/``, ``testbed/``.
+Only ``prefix/`` matters to the build: ``prefix/lib`` feeds ``jniLibs`` (via
+``stage.jnilibs.stage_runtime_libs``) and ``prefix/lib/pythonX.Y`` (minus
+``lib-dynload``) feeds the asset bundle.
+"""
+
+from __future__ import annotations
+
+import shutil
+import tarfile
+from pathlib import Path
+
+
+class RuntimeStageError(Exception):
+    pass
+
+
+def extract_runtime(tarball: Path, dest: Path) -> Path:
+    """Extract ``tarball`` into ``dest`` and return the ``prefix`` directory.
+
+    Idempotent per destination: an existing extraction is replaced (the
+    tarball's SHA-256 was verified by the collect step before this runs).
+    """
+    if dest.exists():
+        shutil.rmtree(dest)
+    dest.mkdir(parents=True)
+    try:
+        with tarfile.open(tarball, "r:gz") as tf:
+            tf.extractall(dest, filter="data")
+    except (tarfile.TarError, OSError) as exc:
+        raise RuntimeStageError(
+            f"could not extract the python.org runtime {tarball.name}: {exc}"
+        ) from exc
+    prefix = dest / "prefix"
+    if not prefix.is_dir():
+        # Tolerate a single wrapping directory around the documented layout.
+        candidates = [p / "prefix" for p in dest.iterdir() if p.is_dir()]
+        matches = [c for c in candidates if c.is_dir()]
+        if len(matches) == 1:
+            prefix = matches[0]
+        else:
+            raise RuntimeStageError(
+                f"{tarball.name} does not contain the documented prefix/ "
+                f"layout (android/03 channel 2); found: "
+                f"{[p.name for p in dest.iterdir()]}"
+            )
+    return prefix
+
+
+def stdlib_dir(prefix: Path, python_stem: str) -> Path:
+    """``prefix`` -> the pure-Python stdlib tree (``lib/pythonX.Y``)."""
+    lib = prefix / "lib" / python_stem
+    if not lib.is_dir():
+        raise RuntimeStageError(
+            f"runtime prefix has no stdlib at {lib}; the embeddable package "
+            f"layout changed — re-lock and report if this persists."
+        )
+    return lib

kivyforge/platforms/android/stage/wheels.py

@@ -0,0 +1,106 @@
+"""Install locked wheels per ABI (android/06 build step 4).
+
+The lock holds the full transitive set with URLs/hashes, so installation is
+``pip install --no-deps --target`` on the **verified local wheel files** — pip
+never re-resolves and never touches an index. Wheel selection per ABI applies
+the tag-floor rule (an ``android_<api>_<abi>`` wheel with ``api <= min_sdk``;
+highest compatible api wins) plus the shared ``py3-none-any`` entries.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from kivyforge.lock.model import LockedPackage, LockedWheel
+
+
+class WheelStageError(Exception):
+    pass
+
+
+def select_wheel(package: LockedPackage, *, abi: str, min_sdk: int) -> LockedWheel:
+    """Pick the wheel slice this ABI installs (android/01 §tag floor)."""
+    best: tuple[int, LockedWheel] | None = None
+    for wheel in package.wheels:
+        if wheel.is_pure_python:
+            if best is None:
+                best = (-1, wheel)
+            continue
+        tag = wheel.platform_tag
+        parts = tag.split("_", 2)
+        if parts[0] != "android" or len(parts) != 3 or parts[2] != abi:
+            continue
+        try:
+            api = int(parts[1])
+        except ValueError:
+            continue
+        if api <= min_sdk and (best is None or api > best[0]):
+            best = (api, wheel)
+    if best is None:
+        raise WheelStageError(
+            f"{package.name} {package.version} has no wheel for ABI {abi!r} "
+            f"(min_sdk {min_sdk}) in the lock — re-run `kivyforge lock`."
+        )
+    return best[1]
+
+
+def install_wheels(
+    wheel_files: list[Path],
+    target: Path,
+    *,
+    python_version: str,
+    python_executable: str | None = None,
+) -> None:
+    """``pip install --no-deps --target`` the verified wheel files.
+
+    Cross-install: the host interpreter rarely matches the target's version or
+    platform, so the target environment is described explicitly — the platform
+    tags are taken from the selected wheel files themselves (exact match by
+    construction), the version/ABI from the locked target Python.
+    """
+    if not wheel_files:
+        target.mkdir(parents=True, exist_ok=True)
+        return
+    from kivyforge.lock.resolver import abi_tags, pip_python_version
+
+    platforms: list[str] = []
+    for wheel in wheel_files:
+        stem = wheel.name[:-4] if wheel.name.endswith(".whl") else wheel.name
+        tag = stem.rsplit("-", 1)[-1]
+        if tag != "any" and tag not in platforms:
+            platforms.append(tag)
+
+    cmd = [
+        python_executable or sys.executable,
+        "-m",
+        "pip",
+        "install",
+        "--no-deps",
+        "--no-index",
+        "--only-binary=:all:",
+        "--python-version",
+        pip_python_version(python_version),
+        "--implementation",
+        "cp",
+        "--target",
+        str(target),
+        "--quiet",
+    ]
+    for platform_tag in platforms:
+        cmd += ["--platform", platform_tag]
+    for abi in abi_tags(python_version):
+        cmd += ["--abi", abi]
+    cmd += [str(w) for w in wheel_files]
+
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise WheelStageError(
+            "pip could not install the locked wheels into the staging "
+            f"directory.\n  pip said:\n{_indent(proc.stderr or proc.stdout)}"
+        )
+
+
+def _indent(text: str) -> str:
+    return "\n".join(f"    {line}" for line in (text or "").splitlines())

kivyforge/platforms/android/toolchain.py

@@ -0,0 +1,29 @@
+"""kivyforge-emitted Android toolchain pins (android/06 §versioning, layer 2).
+
+These move with a kivyforge release and are validated together — the exact
+combination the Phase-0 prototype proved on-device
+(docs/design/dev/android-loadmodel-findings.md §runtime-package facts). The
+generated project is regenerated on every build, so bumping kivyforge and
+rebuilding is how projects move across these pins.
+"""
+
+from __future__ import annotations
+
+# Gradle wrapper distribution the generated project pins (the python.org
+# testbed's own combo, proven with AGP below).
+GRADLE_VERSION = "8.11.1"
+GRADLE_DISTRIBUTION_URL = (
+    f"https\\://services.gradle.org/distributions/gradle-{GRADLE_VERSION}-bin.zip"
+)
+
+# Android Gradle Plugin version emitted into the root build.gradle.
+AGP_VERSION = "8.10.0"
+
+# Kotlin plugin version (applied only when [tool.kivy.android.src].kotlin is
+# non-empty).
+KOTLIN_VERSION = "1.9.22"
+
+# ndkVersion emitted into app/build.gradle: the launcher compile is
+# deterministic across hosts (android/04 §native launcher). r27.3 is the
+# proven prototype pin; cibuildwheel's wheels pin the same family.
+NDK_VERSION = "27.3.13750724"