kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/windows/launcher/launcher.c

@@ -0,0 +1,379 @@
+/*
+ * kivyforge Windows onedir launcher (bootloader).
+ *
+ * A prebuilt, windowed-subsystem native launcher. One binary serves every app:
+ * everything app-specific lives in the generated bootstrap module, and the only
+ * per-app change to the binary is its icon/version *resources* (patched with
+ * rcedit at package time). See docs/design/platforms/windows/bootloader-windows.md.
+ *
+ * Behavior (spawn-and-wait, NOT exec):
+ *   1. Self-locate via GetModuleFileNameW (loop on ERROR_INSUFFICIENT_BUFFER;
+ *      never a fixed MAX_PATH); derive the bundle layout from the launcher's own
+ *      directory (never trust the CWD).
+ *   2. Set a Unicode child environment: PYTHONHOME=<bundle>\python,
+ *      PYTHONPATH=<bundle>\app, PYTHONNOUSERSITE=1.
+ *   3. Build the child command line
+ *      (<bundle>\python\python.exe <bundle>\_kivyforge_bootstrap.py <argv...>)
+ *      with the correct CommandLineToArgvW-inverse quoting algorithm.
+ *   4. Console handoff: AttachConsole(ATTACH_PARENT_PROCESS). If a parent console
+ *      exists (the `kivyforge run` path), inherit its std handles so the child's
+ *      output/tracebacks reach the terminal. Otherwise (Explorer double-click),
+ *      spawn with CREATE_NO_WINDOW so no console flashes.
+ *   5. CreateProcessW with CREATE_SUSPENDED, assign to a kill-on-close Job
+ *      object, THEN ResumeThread (so no grandchild escapes the job). The job is
+ *      best-effort: on the rare host where it cannot be armed/assigned the app
+ *      still launches, just without the kill-on-close guarantee.
+ *   6. WaitForSingleObject -> GetExitCodeProcess -> exit with the child's code.
+ *      Close every handle on every path.
+ *
+ * Linked /SUBSYSTEM:WINDOWS (windowed only; console apps are out of scope).
+ */
+
+#ifndef UNICODE
+#define UNICODE
+#endif
+#ifndef _UNICODE
+#define _UNICODE
+#endif
+
+#include <windows.h>
+#include <shellapi.h>
+#include <stddef.h>
+
+/* Fixed convention names (see bootloader-windows.md / windows-spec). */
+static const wchar_t *PYTHON_REL = L"\\python\\python.exe";
+static const wchar_t *BOOTSTRAP_REL = L"\\_kivyforge_bootstrap.py";
+static const wchar_t *PYTHONHOME_REL = L"\\python";
+static const wchar_t *PYTHONPATH_REL = L"\\app";
+
+/* Exit code for a launcher-internal failure (distinct from any app exit code).
+ * 71 == EX_OSERR, matching the macOS/Linux launchers. */
+#define LAUNCHER_EX_OSERR 71
+
+/* ----------------------------------------------------------------------------
+ * Small heap helpers. On OOM we fail hard with the OS-error exit code; there is
+ * no meaningful recovery for a launcher.
+ * ------------------------------------------------------------------------- */
+static void *xalloc(size_t bytes) {
+    void *p = HeapAlloc(GetProcessHeap(), 0, bytes);
+    return p;
+}
+
+static void xfree(void *p) {
+    if (p != NULL) {
+        HeapFree(GetProcessHeap(), 0, p);
+    }
+}
+
+/* ----------------------------------------------------------------------------
+ * Self-location: GetModuleFileNameW into a growable buffer. Returns a
+ * heap-allocated wide string (caller frees) or NULL on failure.
+ * ------------------------------------------------------------------------- */
+static wchar_t *module_path(void) {
+    DWORD cap = MAX_PATH;
+    for (;;) {
+        wchar_t *buf = (wchar_t *)xalloc(cap * sizeof(wchar_t));
+        if (buf == NULL) {
+            return NULL;
+        }
+        DWORD n = GetModuleFileNameW(NULL, buf, cap);
+        if (n == 0) {
+            xfree(buf);
+            return NULL;
+        }
+        if (n < cap && GetLastError() != ERROR_INSUFFICIENT_BUFFER) {
+            /* n < cap means the name fit (and is NUL-terminated). */
+            return buf;
+        }
+        xfree(buf);
+        if (cap > (1 << 20)) {
+            /* Runaway guard: no sane path is a million wchars. */
+            return NULL;
+        }
+        cap *= 2;
+    }
+}
+
+/* Return the length of *path up to (not including) the final backslash — i.e.
+ * the directory portion. If there is no backslash, returns 0. */
+static size_t dir_len(const wchar_t *path) {
+    size_t last = 0;
+    for (size_t i = 0; path[i] != L'\0'; i++) {
+        if (path[i] == L'\\') {
+            last = i;
+        }
+    }
+    return last;
+}
+
+/* Concatenate dir[0..dir_count) + suffix into a fresh heap string. */
+static wchar_t *join(const wchar_t *dir, size_t dir_count, const wchar_t *suffix) {
+    size_t slen = 0;
+    while (suffix[slen] != L'\0') {
+        slen++;
+    }
+    wchar_t *out = (wchar_t *)xalloc((dir_count + slen + 1) * sizeof(wchar_t));
+    if (out == NULL) {
+        return NULL;
+    }
+    for (size_t i = 0; i < dir_count; i++) {
+        out[i] = dir[i];
+    }
+    for (size_t i = 0; i < slen; i++) {
+        out[dir_count + i] = suffix[i];
+    }
+    out[dir_count + slen] = L'\0';
+    return out;
+}
+
+/* ----------------------------------------------------------------------------
+ * Argv quoting — the exact inverse of CommandLineToArgvW (Daniel Colascione's
+ * documented algorithm). Naive double-quoting corrupts paths ending in `\` and
+ * any argument containing a `"`. Appends the quoted form of *arg to the buffer.
+ * ------------------------------------------------------------------------- */
+
+typedef struct {
+    wchar_t *data;
+    size_t len;
+    size_t cap;
+    int oom;
+} WBuf;
+
+static void wbuf_init(WBuf *b) {
+    b->cap = 256;
+    b->len = 0;
+    b->oom = 0;
+    b->data = (wchar_t *)xalloc(b->cap * sizeof(wchar_t));
+    if (b->data == NULL) {
+        b->oom = 1;
+    }
+}
+
+static void wbuf_push(WBuf *b, wchar_t c) {
+    if (b->oom) {
+        return;
+    }
+    if (b->len + 1 >= b->cap) {
+        size_t ncap = b->cap * 2;
+        wchar_t *nd = (wchar_t *)xalloc(ncap * sizeof(wchar_t));
+        if (nd == NULL) {
+            b->oom = 1;
+            return;
+        }
+        for (size_t i = 0; i < b->len; i++) {
+            nd[i] = b->data[i];
+        }
+        xfree(b->data);
+        b->data = nd;
+        b->cap = ncap;
+    }
+    b->data[b->len++] = c;
+}
+
+static void wbuf_push_str(WBuf *b, const wchar_t *s) {
+    for (size_t i = 0; s[i] != L'\0'; i++) {
+        wbuf_push(b, s[i]);
+    }
+}
+
+/* Append *arg, quoted iff necessary, to *b (per CommandLineToArgvW rules). */
+static void append_quoted(WBuf *b, const wchar_t *arg) {
+    int needs_quotes = (arg[0] == L'\0');
+    for (size_t i = 0; arg[i] != L'\0'; i++) {
+        if (arg[i] == L' ' || arg[i] == L'\t' || arg[i] == L'"') {
+            needs_quotes = 1;
+            break;
+        }
+    }
+    if (!needs_quotes) {
+        wbuf_push_str(b, arg);
+        return;
+    }
+    wbuf_push(b, L'"');
+    for (size_t i = 0;; i++) {
+        size_t backslashes = 0;
+        while (arg[i] == L'\\') {
+            i++;
+            backslashes++;
+        }
+        if (arg[i] == L'\0') {
+            /* Escape all backslashes, but let the terminating quote be added
+             * after; the backslashes must not eat that quote. */
+            for (size_t k = 0; k < backslashes * 2; k++) {
+                wbuf_push(b, L'\\');
+            }
+            break;
+        } else if (arg[i] == L'"') {
+            /* Escape all backslashes and the following quote. */
+            for (size_t k = 0; k < backslashes * 2 + 1; k++) {
+                wbuf_push(b, L'\\');
+            }
+            wbuf_push(b, arg[i]);
+        } else {
+            /* Backslashes are not special here. */
+            for (size_t k = 0; k < backslashes; k++) {
+                wbuf_push(b, L'\\');
+            }
+            wbuf_push(b, arg[i]);
+        }
+    }
+    wbuf_push(b, L'"');
+}
+
+/* ----------------------------------------------------------------------------
+ * Entry point. /SUBSYSTEM:WINDOWS with the Unicode CRT startup calls wWinMain.
+ * We ignore its args and pull the real command line via GetCommandLineW so we
+ * get wide-char argv regardless.
+ * ------------------------------------------------------------------------- */
+int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
+                    LPWSTR lpCmdLine, int nCmdShow) {
+    (void)hInstance;
+    (void)hPrevInstance;
+    (void)lpCmdLine;
+    (void)nCmdShow;
+
+    wchar_t *exe = module_path();
+    if (exe == NULL) {
+        return LAUNCHER_EX_OSERR;
+    }
+    size_t bundle_len = dir_len(exe); /* index of the last backslash */
+
+    wchar_t *python = join(exe, bundle_len, PYTHON_REL);
+    wchar_t *bootstrap = join(exe, bundle_len, BOOTSTRAP_REL);
+    wchar_t *pyhome = join(exe, bundle_len, PYTHONHOME_REL);
+    wchar_t *pypath = join(exe, bundle_len, PYTHONPATH_REL);
+    if (python == NULL || bootstrap == NULL || pyhome == NULL || pypath == NULL) {
+        return LAUNCHER_EX_OSERR;
+    }
+
+    /* Child environment: inherit ours, then override the Python isolation vars.
+     * SetEnvironmentVariableW mutates this process's block, which the child
+     * inherits (we pass a NULL environment to CreateProcessW). */
+    SetEnvironmentVariableW(L"PYTHONHOME", pyhome);
+    SetEnvironmentVariableW(L"PYTHONPATH", pypath);
+    SetEnvironmentVariableW(L"PYTHONNOUSERSITE", L"1");
+
+    /* Reconstruct the child command line: python.exe, the bootstrap, then every
+     * forwarded argument (argv[1..]) quoted correctly. */
+    int argc = 0;
+    LPWSTR *argv = CommandLineToArgvW(GetCommandLineW(), &argc);
+    if (argv == NULL) {
+        return LAUNCHER_EX_OSERR;
+    }
+    WBuf cmd;
+    wbuf_init(&cmd);
+    append_quoted(&cmd, python);
+    wbuf_push(&cmd, L' ');
+    append_quoted(&cmd, bootstrap);
+    for (int i = 1; i < argc; i++) {
+        wbuf_push(&cmd, L' ');
+        append_quoted(&cmd, argv[i]);
+    }
+    wbuf_push(&cmd, L'\0');
+    LocalFree(argv);
+    if (cmd.oom) {
+        return LAUNCHER_EX_OSERR;
+    }
+
+    /* Console handoff. A windowed-subsystem process does not reliably inherit a
+     * parent console's std handles; make the handoff explicit. */
+    BOOL attached = AttachConsole(ATTACH_PARENT_PROCESS);
+    DWORD creation_flags = CREATE_SUSPENDED;
+    STARTUPINFOW si;
+    ZeroMemory(&si, sizeof(si));
+    si.cb = sizeof(si);
+    BOOL inherit_handles = FALSE;
+    if (attached) {
+        /* Pass the attached terminal's std handles to the console-subsystem
+         * child so prints/tracebacks land where the developer is looking. */
+        HANDLE hin = GetStdHandle(STD_INPUT_HANDLE);
+        HANDLE hout = GetStdHandle(STD_OUTPUT_HANDLE);
+        HANDLE herr = GetStdHandle(STD_ERROR_HANDLE);
+        si.dwFlags |= STARTF_USESTDHANDLES;
+        si.hStdInput = hin;
+        si.hStdOutput = hout;
+        si.hStdError = herr;
+        SetHandleInformation(hin, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT);
+        SetHandleInformation(hout, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT);
+        SetHandleInformation(herr, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT);
+        inherit_handles = TRUE;
+    } else {
+        /* No parent console (Explorer double-click): suppress the console flash
+         * that a console-subsystem python.exe would otherwise create.
+         *
+         * Why CREATE_NO_WINDOW on python.exe rather than launching pythonw.exe:
+         * a single code path serves both entry points. On the `kivyforge run`
+         * path we WANT the console-subsystem python.exe so its stdout/stderr and
+         * tracebacks attach to the parent terminal (above). Using pythonw.exe for
+         * double-click would mean detecting the mode and choosing a different
+         * child, and pythonw.exe forfeits that attach-for-diagnostics story. One
+         * child + CREATE_NO_WINDOW gives silent double-click AND visible `run`. */
+        creation_flags |= CREATE_NO_WINDOW;
+    }
+
+    /* A Job object with kill-on-close makes the whole child process tree die
+     * with the launcher (Ctrl-C, task kill, crash) — no orphaned python. This
+     * is best-effort: if the job cannot be established (rare on Win8+ where
+     * nested jobs are the default), we drop it and still launch rather than
+     * refuse to start the app. Failing calls are checked, never ignored. */
+    HANDLE job = CreateJobObjectW(NULL, NULL);
+    if (job != NULL) {
+        JOBOBJECT_EXTENDED_LIMIT_INFORMATION jeli;
+        ZeroMemory(&jeli, sizeof(jeli));
+        jeli.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
+        if (!SetInformationJobObject(job, JobObjectExtendedLimitInformation, &jeli,
+                                     sizeof(jeli))) {
+            /* A job we cannot arm for kill-on-close is worse than none: close it
+             * so we do not rely on a half-configured job below. */
+            CloseHandle(job);
+            job = NULL;
+        }
+    }
+
+    PROCESS_INFORMATION pi;
+    ZeroMemory(&pi, sizeof(pi));
+    BOOL ok = CreateProcessW(python,        /* application: the bundled python */
+                             cmd.data,      /* full command line */
+                             NULL, NULL,    /* default security */
+                             inherit_handles,
+                             creation_flags,
+                             NULL,          /* inherit our (mutated) environment */
+                             NULL,          /* inherit CWD; bootstrap sets its own */
+                             &si, &pi);
+    if (!ok) {
+        if (job != NULL) {
+            CloseHandle(job);
+        }
+        return LAUNCHER_EX_OSERR;
+    }
+
+    /* Assign to the job while still suspended (closes the grandchild-escape
+     * race), THEN resume the main thread. If assignment fails we cannot promise
+     * kill-on-close, so drop the job rather than pretend the guarantee holds. */
+    if (job != NULL && !AssignProcessToJobObject(job, pi.hProcess)) {
+        CloseHandle(job);
+        job = NULL;
+    }
+    if (ResumeThread(pi.hThread) == (DWORD)-1) {
+        /* The child is stuck suspended; never WaitForSingleObject forever on it.
+         * Tear it down deterministically and report an OS error. */
+        TerminateProcess(pi.hProcess, LAUNCHER_EX_OSERR);
+        CloseHandle(pi.hThread);
+        CloseHandle(pi.hProcess);
+        if (job != NULL) {
+            CloseHandle(job);
+        }
+        return LAUNCHER_EX_OSERR;
+    }
+
+    WaitForSingleObject(pi.hProcess, INFINITE);
+    DWORD code = LAUNCHER_EX_OSERR;
+    GetExitCodeProcess(pi.hProcess, &code);
+
+    CloseHandle(pi.hThread);
+    CloseHandle(pi.hProcess);
+    if (job != NULL) {
+        CloseHandle(job);
+    }
+    return (int)code;
+}

kivyforge/platforms/windows/lock/__init__.py

@@ -0,0 +1,112 @@
+"""Windows lock stack (``pylock.windows.toml``).
+
+A thin Windows *profile* (:class:`WindowsProfile`) over the generic
+wheel+runtime lock engine (``kivyforge.lock.wheelruntime``). This module is the
+stable Windows public surface: it binds the profile into the core and re-exports
+the engine's types under Windows-friendly names so callers (the CLI, tests)
+never reach into the generic package directly.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+
+from kivyforge.config.model import Config
+from kivyforge.lock.wheelruntime import (
+    PythonRuntime as WindowsPythonRuntime,
+)
+from kivyforge.lock.wheelruntime import (
+    ResolvedPackage,
+    ResolvedWheel,
+    RuntimeArtifact,
+    RuntimeProvider,
+    RuntimeProviderError,
+    Variant,
+    WheelResolver,
+    WheelResolverError,
+    WheelRuntimeBuildError,
+    WheelRuntimeLock,
+    build_wheel_runtime_lock,
+    diff_summary,
+    get_wheel_resolver,
+    semantic_equal,
+)
+from kivyforge.lock.wheelruntime import serialize as _ser
+
+from .profile import WindowsProfile, wheel_arch, windows_platform_tag
+from .runtime import PythonBuildStandaloneProvider
+
+# Windows-friendly aliases for the generic engine types.
+WindowsLockfile = WheelRuntimeLock
+WindowsBuildError = WheelRuntimeBuildError
+WindowsResolverError = WheelResolverError
+
+_PROFILE = WindowsProfile()
+
+__all__ = [
+    "PythonBuildStandaloneProvider",
+    "ResolvedPackage",
+    "ResolvedWheel",
+    "RuntimeArtifact",
+    "RuntimeProvider",
+    "RuntimeProviderError",
+    "Variant",
+    "WheelResolver",
+    "WindowsBuildError",
+    "WindowsLockfile",
+    "WindowsProfile",
+    "WindowsPythonRuntime",
+    "WindowsResolverError",
+    "build_windows_lockfile",
+    "diff_summary",
+    "dumps",
+    "get_windows_resolver",
+    "load",
+    "loads",
+    "semantic_equal",
+    "wheel_arch",
+    "windows_platform_tag",
+]
+
+
+def build_windows_lockfile(
+    config: Config,
+    pyproject_text: str,
+    *,
+    project_root: Path | None = None,
+    resolver: WheelResolver | None = None,
+    runtime_provider: RuntimeProvider | None = None,
+    offline: bool = False,
+    now: datetime | None = None,
+    on_warning: Callable[[str], None] | None = None,
+) -> WindowsLockfile:
+    return build_wheel_runtime_lock(
+        _PROFILE,
+        config,
+        pyproject_text,
+        project_root=project_root,
+        resolver=resolver,
+        runtime_provider=runtime_provider,
+        native_binaries=config.windows.binaries if config.windows else (),
+        offline=offline,
+        now=now,
+        on_warning=on_warning,
+    )
+
+
+def dumps(lock: WindowsLockfile) -> str:
+    return _ser.dumps(lock)
+
+
+def loads(text: str) -> WindowsLockfile:
+    return _ser.loads(text, platform="windows")
+
+
+def load(path: str | Path) -> WindowsLockfile:
+    return _ser.load(path, platform="windows")
+
+
+def get_windows_resolver(backend: str = "pip", **kwargs) -> WheelResolver:
+    return get_wheel_resolver(backend, **kwargs)

kivyforge/platforms/windows/lock/profile.py

@@ -0,0 +1,101 @@
+"""Windows lock profile — the platform-specific inputs to the wheel+runtime core.
+
+The simplest of the desktop family: Windows has a single stable wheel platform
+tag per arch (``win_amd64`` this phase — ``win32``/``win_arm64`` are out of
+scope), so there is no tag ladder (Linux) and no fat-wheel arch (macOS
+``universal2``). ``kivy_deps.*`` are ordinary wheels — Kivy's ``win_amd64`` wheel
+declares them as conditional dependencies, so they flow through the shared
+resolver with URL + SHA-256 pins with no special-casing. The bundled runtime
+comes from python-build-standalone (``x86_64-pc-windows-msvc``). Everything else
+— resolve/serialize/build orchestration — is the shared core.
+"""
+
+from __future__ import annotations
+
+from kivyforge.config.errors import ConfigError
+from kivyforge.config.model import Config
+from kivyforge.lock.wheelruntime.profile import PlatformLockProfile
+from kivyforge.lock.wheelruntime.resolver import Variant
+from kivyforge.lock.wheelruntime.runtime import RuntimeProvider
+
+from .runtime import PythonBuildStandaloneProvider
+
+# arm64: add "arm64" here and "arm64": "win_arm64" to _ARCH_TO_TAG; _TAG_TO_ARCH
+# derives automatically, and coverage_error's "win_amd64" text should generalize
+# to the per-arch tag. Gated on upstream win_arm64 wheels — see arm64-windows.md §2.
+VALID_WHEEL_ARCHS = frozenset({"amd64"})
+
+# kivyforge arch name -> the wheel platform tag pip requests / a wheel carries.
+_ARCH_TO_TAG = {"amd64": "win_amd64"}
+_TAG_TO_ARCH = {tag: arch for arch, tag in _ARCH_TO_TAG.items()}
+
+
+def windows_platform_tag(arch: str) -> str:
+    """The pip ``--platform`` tag for a Windows arch (``amd64`` -> ``win_amd64``)."""
+    return _ARCH_TO_TAG[arch]
+
+
+def wheel_arch(platform_tag: str) -> str | None:
+    """The architecture a Windows wheel platform tag targets, or ``None``.
+
+    ``win_amd64`` -> ``amd64``. ``win32`` (x86) and ``win_arm64`` are recognized
+    as Windows tags but are unsupported this phase, so they resolve to their arch
+    name only if that arch is a valid target (they are not), i.e. ``None`` here.
+    A non-Windows tag (``any`` is handled by the shared core) also returns
+    ``None``.
+    """
+    return _TAG_TO_ARCH.get(platform_tag)
+
+
+class WindowsProfile(PlatformLockProfile):
+    platform = "windows"
+
+    def overlay(self, config: Config):
+        return config.windows
+
+    def missing_overlay_error(self) -> str:
+        return "pyproject.toml has no [tool.kivy.windows] table; nothing to lock."
+
+    def python_version(self, config: Config) -> str:
+        # [tool.kivy.windows.python].version is required (the loader raises a
+        # ConfigError when it is missing), so it is always set here. Never
+        # silently substitute a hidden default — that would pin an unexpected
+        # (and possibly unreleased) Python instead of surfacing the misconfig.
+        version = config.windows_required.python_version
+        if not version:
+            raise ConfigError(
+                "missing required [tool.kivy.windows.python].version",
+                key_path="tool.kivy.windows.python.version",
+            )
+        return version
+
+    def variants(self, config: Config) -> tuple[Variant, ...]:
+        return tuple(
+            Variant(arch=arch, platform_tag=windows_platform_tag(arch))
+            for arch in config.windows_required.archs
+        )
+
+    def wheel_covers(self, platform_tag: str, archs: tuple[str, ...]) -> set[str]:
+        arch = wheel_arch(platform_tag)
+        if arch in archs:
+            return {arch}
+        return set()
+
+    def runtime_provider(self, config: Config) -> RuntimeProvider:
+        return PythonBuildStandaloneProvider()
+
+    def coverage_error(self, name: str, missing: list[str]) -> str:
+        return (
+            f"{name} has no win_amd64 wheel for arch(es): {', '.join(missing)}.\n"
+            f"  A compiled package must publish a win_amd64 wheel to be locked "
+            f"reproducibly.\n"
+            f"  Supply the wheel via extra_index_urls/find_links, or drop the "
+            f"dependency on Windows."
+        )
+
+    def wheel_scope_hint(self) -> str:
+        return (
+            "Vendored wheels must live under the project directory, a sibling "
+            "directory, or the enclosing repository (e.g. a wheels/ directory "
+            "beside pyproject.toml)."
+        )

kivyforge/platforms/windows/lock/runtime.py

@@ -0,0 +1,64 @@
+"""Windows runtime provider — python-build-standalone with the msvc triple.
+
+A one-line specialization of the generic :class:`PbsProvider`: it fixes the
+arch→target-triple map to Windows's ``x86_64-pc-windows-msvc`` build, and
+otherwise inherits the shared PBS resolution + injectable metadata fetcher. The
+Windows ``install_only`` archive normalizes under the same top-level ``python/``
+tree as the darwin/linux ones (a normal relocatable prefix — ``python.exe`` at
+the root, ``Lib/site-packages`` beneath it), which is load-bearing: staging must
+**not** flatten, prune, or ``._pth``-isolate it (windows-spec).
+"""
+
+from __future__ import annotations
+
+from kivyforge.lock.wheelruntime.runtime import (
+    MetadataFetcher,
+    PbsProvider,
+    ReleaseAsset,
+    RuntimeProvider,
+    RuntimeProviderError,
+    pbs_asset_glob,
+)
+
+__all__ = [
+    "PythonBuildStandaloneProvider",
+    "ReleaseAsset",
+    "RuntimeProvider",
+    "RuntimeProviderError",
+    "WINDOWS_TRIPLES",
+    "get_runtime_provider",
+    "pbs_asset_name",
+]
+
+# kivyforge arch name -> PBS/LLVM Windows target triple.
+# arm64: add "arm64": "aarch64-pc-windows-msvc" (confirm PBS ships that
+# install_only archive for the pinned CPython). The generic PbsProvider handles
+# the rest — no other change here. See arm64-windows.md §3.
+WINDOWS_TRIPLES = {
+    "amd64": "x86_64-pc-windows-msvc",
+}
+
+# Windows-facing alias for the generic PBS asset glob helper.
+pbs_asset_name = pbs_asset_glob
+
+
+class PythonBuildStandaloneProvider(PbsProvider):
+    """PBS provider fixed to the Windows msvc triple."""
+
+    def __init__(
+        self,
+        metadata_fetcher: MetadataFetcher | None = None,
+        *,
+        floor: str | None = None,
+    ) -> None:
+        super().__init__(WINDOWS_TRIPLES, metadata_fetcher, floor=floor)
+
+
+def get_runtime_provider(
+    name: str = "python-build-standalone", **kwargs
+) -> RuntimeProvider:
+    if name in ("python-build-standalone", "pbs", "python_build_standalone"):
+        return PythonBuildStandaloneProvider(**kwargs)
+    raise RuntimeProviderError(
+        f"unknown runtime provider {name!r} (expected python-build-standalone)"
+    )