a3s-code 8.0.2__tar.gz → 8.0.3__tar.gz

{a3s_code-8.0.2 → a3s_code-8.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: a3s-code
-Version: 8.0.2
+Version: 8.0.3
 Summary: A3S Code Python SDK — pure-Python bootstrap that fetches the native wheel from GitHub Releases
 Author: A3S Lab
 License: MIT
@@ -9,6 +9,11 @@ Project-URL: Repository, https://github.com/A3S-Lab/Code
 Project-URL: Issues, https://github.com/A3S-Lab/Code/issues
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development
@@ -19,13 +24,22 @@ Description-Content-Type: text/markdown
 
 `pip install a3s-code` ships this small pure-Python package. On first
 `import a3s_code` it downloads the native extension matching your
-interpreter and platform from the project's
+platform from the project's
 [GitHub Releases](https://github.com/A3S-Lab/Code/releases), verifies
 the wheel's sha256 against the release manifest, extracts the compiled
 extension into a per-user cache, and exposes the normal `a3s_code` API.
 
-Subsequent imports use the cached extension. Cache lives under
-`~/.cache/a3s-code/<version>/` (or `$XDG_CACHE_HOME/a3s-code/<version>/`).
+The v8.0.3 release uses one CPython 3.10 stable-ABI (`cp310-abi3`) wheel per
+platform. That wheel is installable by CPython 3.10, 3.11, 3.12, 3.13, and
+3.14. The published `v8.0.2` assets predate this workflow and still use exact
+CPython 3.10–3.13 wheel names; upgrade the bootstrap to v8.0.3 for Python
+3.14. The loader falls back to the exact per-minor names used by older
+releases, so upgrading the bootstrap does not invalidate an older release
+asset.
+
+Subsequent imports use the cached extension. Cache lives under a
+platform-specific directory, `~/.cache/a3s-code/<version>/<platform-tag>/`
+(or `$A3S_CODE_CACHE_DIR/<version>/<platform-tag>/` when overridden).
 
 ## Why
 
@@ -42,10 +56,16 @@ through PyPI.
 - Linux x86_64 (glibc 2.28+)
 - Windows x86_64
 
-CPython 3.10, 3.11, 3.12, 3.13.
+CPython 3.10, 3.11, 3.12, 3.13, and 3.14.
 
-Python 3.14 wheels are not published yet. Use CPython 3.13 or earlier until
-the native binding is rebuilt for Python 3.14.
+The bootstrap itself needs a working pip in the interpreter that runs it. If
+`python3.14 -m pip` reports `No module named pip`, initialize pip and retry:
+
+```bash
+python3.14 -m ensurepip --upgrade
+python3.14 -m pip install --upgrade pip
+python3.14 -m pip install a3s-code
+```
 
 ## Environment overrides
 
@@ -62,15 +82,19 @@ wheel directly:
 
 ```bash
 pip install \
-  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp312-cp312-manylinux_2_28_x86_64.whl'
+  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp310-abi3-manylinux_2_28_x86_64.whl'
 ```
 
 For an Intel Mac on macOS 12 or later, use the `macosx_12_0_x86_64` asset:
 
 ```bash
 pip install \
-  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp312-cp312-macosx_12_0_x86_64.whl'
+  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp310-abi3-macosx_12_0_x86_64.whl'
 ```
 
 Replace `<VERSION>` with the release to install. The Intel asset is available
 from the first release produced with the Intel build matrix.
+
+The Intel macOS 12 build does not ship the optional local ONNX embedding
+adapter. Keep retrieval model-free or configure an explicitly authorized
+remote embedding provider when using that platform.

{a3s_code-8.0.2 → a3s_code-8.0.3}/README.md

@@ -2,13 +2,22 @@
 
 `pip install a3s-code` ships this small pure-Python package. On first
 `import a3s_code` it downloads the native extension matching your
-interpreter and platform from the project's
+platform from the project's
 [GitHub Releases](https://github.com/A3S-Lab/Code/releases), verifies
 the wheel's sha256 against the release manifest, extracts the compiled
 extension into a per-user cache, and exposes the normal `a3s_code` API.
 
-Subsequent imports use the cached extension. Cache lives under
-`~/.cache/a3s-code/<version>/` (or `$XDG_CACHE_HOME/a3s-code/<version>/`).
+The v8.0.3 release uses one CPython 3.10 stable-ABI (`cp310-abi3`) wheel per
+platform. That wheel is installable by CPython 3.10, 3.11, 3.12, 3.13, and
+3.14. The published `v8.0.2` assets predate this workflow and still use exact
+CPython 3.10–3.13 wheel names; upgrade the bootstrap to v8.0.3 for Python
+3.14. The loader falls back to the exact per-minor names used by older
+releases, so upgrading the bootstrap does not invalidate an older release
+asset.
+
+Subsequent imports use the cached extension. Cache lives under a
+platform-specific directory, `~/.cache/a3s-code/<version>/<platform-tag>/`
+(or `$A3S_CODE_CACHE_DIR/<version>/<platform-tag>/` when overridden).
 
 ## Why
 
@@ -25,10 +34,16 @@ through PyPI.
 - Linux x86_64 (glibc 2.28+)
 - Windows x86_64
 
-CPython 3.10, 3.11, 3.12, 3.13.
+CPython 3.10, 3.11, 3.12, 3.13, and 3.14.
 
-Python 3.14 wheels are not published yet. Use CPython 3.13 or earlier until
-the native binding is rebuilt for Python 3.14.
+The bootstrap itself needs a working pip in the interpreter that runs it. If
+`python3.14 -m pip` reports `No module named pip`, initialize pip and retry:
+
+```bash
+python3.14 -m ensurepip --upgrade
+python3.14 -m pip install --upgrade pip
+python3.14 -m pip install a3s-code
+```
 
 ## Environment overrides
 
@@ -45,15 +60,19 @@ wheel directly:
 
 ```bash
 pip install \
-  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp312-cp312-manylinux_2_28_x86_64.whl'
+  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp310-abi3-manylinux_2_28_x86_64.whl'
 ```
 
 For an Intel Mac on macOS 12 or later, use the `macosx_12_0_x86_64` asset:
 
 ```bash
 pip install \
-  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp312-cp312-macosx_12_0_x86_64.whl'
+  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp310-abi3-macosx_12_0_x86_64.whl'
 ```
 
 Replace `<VERSION>` with the release to install. The Intel asset is available
 from the first release produced with the Intel build matrix.
+
+The Intel macOS 12 build does not ship the optional local ONNX embedding
+adapter. Keep retrieval model-free or configure an explicitly authorized
+remote embedding provider when using that platform.

{a3s_code-8.0.2 → a3s_code-8.0.3}/pyproject.toml

@@ -7,7 +7,7 @@ name = "a3s-code"
 # Keep in sync with crates/code core release. The bootstrap loader fetches
 # the matching native wheel from `https://github.com/A3S-Lab/Code/releases/tag/v<version>`
 # at import time.
-version = "8.0.2"
+version = "8.0.3"
 description = "A3S Code Python SDK — pure-Python bootstrap that fetches the native wheel from GitHub Releases"
 readme = "README.md"
 license = {text = "MIT"}
@@ -18,6 +18,11 @@ authors = [
 classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Topic :: Software Development",

{a3s_code-8.0.2 → a3s_code-8.0.3}/src/a3s_code/__init__.py

@@ -10,9 +10,8 @@ from . import _bootstrap as _bootstrap
 
 _bootstrap.ensure_native_loaded()
 
-# Re-import after the cache dir is on sys.path. The bootstrap extracted
-# `_native.<abi>.so` into a per-version cache; Python's import machinery
-# picks it up from there.
+# The bootstrap extracted `_native.<abi>.so` into a per-version cache and
+# registered it explicitly as `a3s_code._native` before returning.
 from ._native import *  # noqa: E402,F401,F403
 
 __version__ = _bootstrap.__version__

{a3s_code-8.0.2 → a3s_code-8.0.3}/src/a3s_code/_bootstrap.py

@@ -1,12 +1,12 @@
 """Lazy loader for the a3s-code native extension.
 
 This module is part of the pure-Python bootstrap published to PyPI under
-the `a3s-code` name. On first import it resolves the matching native
-wheel for the current interpreter/platform, downloads it from the
-project's GitHub Releases, verifies the wheel's sha256 against the
+the `a3s-code` name. On first import it resolves a compatible native
+wheel for the current platform, downloads it from the project's GitHub
+Releases, verifies the wheel's sha256 against the
 release manifest, extracts the compiled `_native` extension into a
-per-user cache, and prepends the cache to `sys.path` so the rest of
-`a3s_code/__init__.py` can `from ._native import *` normally.
+per-user cache, and registers it explicitly as `a3s_code._native` because it
+lives outside the installed package directory.
 
 Override the cache location via `A3S_CODE_CACHE_DIR`. Override the
 release source via `A3S_CODE_RELEASES_BASE_URL` (default points at the
@@ -31,11 +31,13 @@ from typing import Optional
 
 # Version is the bootstrap's own version, which equals the matching native
 # wheel version on GH Releases. Bumped by the release workflow.
-__version__ = "8.0.2"
+__version__ = "8.0.3"
 
 _DEFAULT_BASE_URL = "https://github.com/A3S-Lab/Code/releases/download"
 _REQUEST_TIMEOUT_S = 120
 _USER_AGENT = f"a3s-code-bootstrap/{__version__}"
+_MIN_PYTHON = (3, 10)
+_ABI3_PYTHON_TAG = "cp310-abi3"
 _LOAD_LOCK = threading.Lock()
 _LOADED = False
 
@@ -44,6 +46,15 @@ class BootstrapError(RuntimeError):
     """Raised when the native extension cannot be located, downloaded, or verified."""
 
 
+class BootstrapHttpError(BootstrapError):
+    """HTTP failure with a status code that callers can safely classify."""
+
+    def __init__(self, url: str, status_code: int):
+        self.url = url
+        self.status_code = status_code
+        super().__init__(f"GET {url} failed: HTTP {status_code}")
+
+
 def _base_url() -> str:
     return os.environ.get("A3S_CODE_RELEASES_BASE_URL", _DEFAULT_BASE_URL).rstrip("/")
 
@@ -51,9 +62,18 @@ def _base_url() -> str:
 def _cache_root() -> Path:
     override = os.environ.get("A3S_CODE_CACHE_DIR")
     if override:
-        return Path(override).expanduser() / __version__
-    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
-    return Path(base) / "a3s-code" / __version__
+        base = Path(override).expanduser() / __version__
+    else:
+        base = (
+            Path(os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache"))
+            / "a3s-code"
+            / __version__
+        )
+    # Keep native binaries for different architectures/OS baselines isolated.
+    # This matters when an Apple Silicon and an Intel interpreter share a home
+    # directory (for example, under Rosetta); a cached arm64 extension must
+    # never be handed to an x86_64 process.
+    return base / _platform_tag()
 
 
 def _platform_tag() -> str:
@@ -86,10 +106,50 @@ def _platform_tag() -> str:
 
 
 def _wheel_filename(version: str = __version__) -> str:
+    if platform.python_implementation() != "CPython":
+        raise BootstrapError(
+            "a3s-code publishes native wheels for CPython only; "
+            f"found {platform.python_implementation()}"
+        )
+    if (sys.version_info.major, sys.version_info.minor) < _MIN_PYTHON:
+        raise BootstrapError(
+            "a3s-code requires CPython 3.10 or newer; "
+            f"found {sys.version_info.major}.{sys.version_info.minor}"
+        )
     py_tag = f"cp{sys.version_info.major}{sys.version_info.minor}"
     return f"a3s_code-{version}-{py_tag}-{py_tag}-{_platform_tag()}.whl"
 
 
+def _abi3_wheel_filename(version: str = __version__) -> str:
+    """Return the stable-ABI wheel name used by current releases."""
+    if platform.python_implementation() != "CPython":
+        raise BootstrapError(
+            "a3s-code publishes native wheels for CPython only; "
+            f"found {platform.python_implementation()}"
+        )
+    if (sys.version_info.major, sys.version_info.minor) < _MIN_PYTHON:
+        raise BootstrapError(
+            "a3s-code requires CPython 3.10 or newer; "
+            f"found {sys.version_info.major}.{sys.version_info.minor}"
+        )
+    return f"a3s_code-{version}-{_ABI3_PYTHON_TAG}-{_platform_tag()}.whl"
+
+
+def _wheel_candidates(version: str = __version__) -> tuple[str, ...]:
+    """Return compatible wheel names in migration-safe preference order.
+
+    Existing releases contain one wheel per CPython minor, so Python 3.10–3.13
+    keep using those exact assets first.  New releases publish a single
+    ``cp310-abi3`` wheel; Python 3.14+ prefers that asset and all interpreters
+    fall back to it when an older release has no exact match.
+    """
+    exact = _wheel_filename(version)
+    abi3 = _abi3_wheel_filename(version)
+    if sys.version_info.minor >= 14:
+        return (abi3, exact)
+    return (exact, abi3)
+
+
 def _release_url(filename: str, version: str = __version__) -> str:
     return f"{_base_url()}/v{version}/{filename}"
 
@@ -100,7 +160,7 @@ def _http_get(url: str) -> bytes:
         with urllib.request.urlopen(req, timeout=_REQUEST_TIMEOUT_S) as resp:
             return resp.read()
     except urllib.error.HTTPError as exc:
-        raise BootstrapError(f"GET {url} failed: HTTP {exc.code}") from exc
+        raise BootstrapHttpError(url, exc.code) from exc
     except urllib.error.URLError as exc:
         raise BootstrapError(f"GET {url} failed: {exc.reason}") from exc
 
@@ -126,6 +186,27 @@ def _expected_sha256(wheel_name: str, version: str = __version__) -> Optional[st
     return None
 
 
+def _download_wheel(version: str) -> tuple[str, bytes]:
+    """Download the first compatible wheel, retaining old-release fallback."""
+    candidates = _wheel_candidates(version)
+    not_found: list[str] = []
+    for wheel_name in candidates:
+        try:
+            return wheel_name, _http_get(_release_url(wheel_name, version))
+        except BootstrapHttpError as exc:
+            if exc.status_code == 404:
+                not_found.append(wheel_name)
+                continue
+            raise
+
+    tried = ", ".join(not_found)
+    raise BootstrapError(
+        "a3s-code: no compatible native wheel was published for "
+        f"CPython {sys.version_info.major}.{sys.version_info.minor} on "
+        f"{sys.platform}/{platform.machine()}. Tried: {tried}"
+    )
+
+
 def _extract_native(wheel_bytes: bytes, target_dir: Path) -> Path:
     """Extract the compiled `_native.*` extension from `wheel_bytes` into
     `target_dir`. Returns the path to the extracted file.
@@ -149,9 +230,23 @@ def _extract_native(wheel_bytes: bytes, target_dir: Path) -> Path:
 def _find_cached_native(cache_dir: Path) -> Optional[Path]:
     if not cache_dir.is_dir():
         return None
-    for child in cache_dir.iterdir():
-        if child.is_file() and child.name.startswith("_native."):
-            return child
+    exact_tag = f"cp{sys.version_info.major}{sys.version_info.minor}"
+    cpython_tag = f"cpython-{sys.version_info.major}{sys.version_info.minor}"
+    exact: list[Path] = []
+    abi3: list[Path] = []
+    for child in sorted(cache_dir.iterdir()):
+        if not child.is_file() or not child.name.startswith("_native."):
+            continue
+        name = child.name.lower()
+        if f".{exact_tag}" in name or cpython_tag in name:
+            exact.append(child)
+        elif ".abi3." in name or name.endswith(".abi3"):
+            abi3.append(child)
+    # Prefer a native build tied to this interpreter, then the stable ABI.
+    if exact:
+        return exact[0]
+    if abi3:
+        return abi3[0]
     return None
 
 
@@ -193,13 +288,12 @@ def ensure_native_loaded(version: str = __version__) -> Path:
 
         native = _find_cached_native(cache)
         if native is None:
-            wheel_name = _wheel_filename(version)
+            wheel_name, wheel_bytes = _download_wheel(version)
             url = _release_url(wheel_name, version)
             sys.stderr.write(
                 f"a3s-code: fetching native wheel {wheel_name} "
                 f"from {url} (first import only)...\n"
             )
-            wheel_bytes = _http_get(url)
 
             if os.environ.get("A3S_CODE_SKIP_HASH_CHECK") != "1":
                 expected = _expected_sha256(wheel_name, version)

{a3s_code-8.0.2 → a3s_code-8.0.3}/src/a3s_code.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: a3s-code
-Version: 8.0.2
+Version: 8.0.3
 Summary: A3S Code Python SDK — pure-Python bootstrap that fetches the native wheel from GitHub Releases
 Author: A3S Lab
 License: MIT
@@ -9,6 +9,11 @@ Project-URL: Repository, https://github.com/A3S-Lab/Code
 Project-URL: Issues, https://github.com/A3S-Lab/Code/issues
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development
@@ -19,13 +24,22 @@ Description-Content-Type: text/markdown
 
 `pip install a3s-code` ships this small pure-Python package. On first
 `import a3s_code` it downloads the native extension matching your
-interpreter and platform from the project's
+platform from the project's
 [GitHub Releases](https://github.com/A3S-Lab/Code/releases), verifies
 the wheel's sha256 against the release manifest, extracts the compiled
 extension into a per-user cache, and exposes the normal `a3s_code` API.
 
-Subsequent imports use the cached extension. Cache lives under
-`~/.cache/a3s-code/<version>/` (or `$XDG_CACHE_HOME/a3s-code/<version>/`).
+The v8.0.3 release uses one CPython 3.10 stable-ABI (`cp310-abi3`) wheel per
+platform. That wheel is installable by CPython 3.10, 3.11, 3.12, 3.13, and
+3.14. The published `v8.0.2` assets predate this workflow and still use exact
+CPython 3.10–3.13 wheel names; upgrade the bootstrap to v8.0.3 for Python
+3.14. The loader falls back to the exact per-minor names used by older
+releases, so upgrading the bootstrap does not invalidate an older release
+asset.
+
+Subsequent imports use the cached extension. Cache lives under a
+platform-specific directory, `~/.cache/a3s-code/<version>/<platform-tag>/`
+(or `$A3S_CODE_CACHE_DIR/<version>/<platform-tag>/` when overridden).
 
 ## Why
 
@@ -42,10 +56,16 @@ through PyPI.
 - Linux x86_64 (glibc 2.28+)
 - Windows x86_64
 
-CPython 3.10, 3.11, 3.12, 3.13.
+CPython 3.10, 3.11, 3.12, 3.13, and 3.14.
 
-Python 3.14 wheels are not published yet. Use CPython 3.13 or earlier until
-the native binding is rebuilt for Python 3.14.
+The bootstrap itself needs a working pip in the interpreter that runs it. If
+`python3.14 -m pip` reports `No module named pip`, initialize pip and retry:
+
+```bash
+python3.14 -m ensurepip --upgrade
+python3.14 -m pip install --upgrade pip
+python3.14 -m pip install a3s-code
+```
 
 ## Environment overrides
 
@@ -62,15 +82,19 @@ wheel directly:
 
 ```bash
 pip install \
-  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp312-cp312-manylinux_2_28_x86_64.whl'
+  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp310-abi3-manylinux_2_28_x86_64.whl'
 ```
 
 For an Intel Mac on macOS 12 or later, use the `macosx_12_0_x86_64` asset:
 
 ```bash
 pip install \
-  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp312-cp312-macosx_12_0_x86_64.whl'
+  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp310-abi3-macosx_12_0_x86_64.whl'
 ```
 
 Replace `<VERSION>` with the release to install. The Intel asset is available
 from the first release produced with the Intel build matrix.
+
+The Intel macOS 12 build does not ship the optional local ONNX embedding
+adapter. Keep retrieval model-free or configure an explicitly authorized
+remote embedding provider when using that platform.

{a3s_code-8.0.2 → a3s_code-8.0.3}/tests/test_bootstrap.py

@@ -81,6 +81,55 @@ class WheelFilenameTests(unittest.TestCase):
             "a3s_code-3.2.1-cp312-cp312-macosx_12_0_x86_64.whl",
         )
 
+    def test_macos_intel_abi3(self):
+        with (
+            mock.patch.object(sys, "platform", "darwin"),
+            mock.patch.object(_bootstrap.platform, "machine", return_value="x86_64"),
+            mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 14)),
+        ):
+            self.assertEqual(
+                _bootstrap._abi3_wheel_filename("3.2.1"),
+                "a3s_code-3.2.1-cp310-abi3-macosx_12_0_x86_64.whl",
+            )
+
+    def test_new_python_prefers_abi3_then_exact_fallback(self):
+        with (
+            mock.patch.object(sys, "platform", "darwin"),
+            mock.patch.object(_bootstrap.platform, "machine", return_value="x86_64"),
+            mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 14)),
+        ):
+            self.assertEqual(
+                _bootstrap._wheel_candidates("3.2.1"),
+                (
+                    "a3s_code-3.2.1-cp310-abi3-macosx_12_0_x86_64.whl",
+                    "a3s_code-3.2.1-cp314-cp314-macosx_12_0_x86_64.whl",
+                ),
+            )
+
+    def test_existing_python_prefers_exact_then_abi3(self):
+        with (
+            mock.patch.object(sys, "platform", "darwin"),
+            mock.patch.object(_bootstrap.platform, "machine", return_value="x86_64"),
+            mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 12)),
+        ):
+            self.assertEqual(
+                _bootstrap._wheel_candidates("3.2.1"),
+                (
+                    "a3s_code-3.2.1-cp312-cp312-macosx_12_0_x86_64.whl",
+                    "a3s_code-3.2.1-cp310-abi3-macosx_12_0_x86_64.whl",
+                ),
+            )
+
+    def test_python_below_abi3_floor_raises(self):
+        with (
+            mock.patch.object(sys, "platform", "darwin"),
+            mock.patch.object(_bootstrap.platform, "machine", return_value="x86_64"),
+            mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 9)),
+        ):
+            with self.assertRaises(_bootstrap.BootstrapError) as cm:
+                _bootstrap._wheel_candidates("3.2.1")
+        self.assertIn("CPython 3.10 or newer", str(cm.exception))
+
     def test_windows_amd64_cp313(self):
         self.assertEqual(
             self._filename_for("win32", "AMD64", 13),
@@ -114,18 +163,31 @@ class CacheDirTests(unittest.TestCase):
 
     def test_default_uses_xdg_or_home(self):
         cache = _bootstrap._cache_root()
-        self.assertEqual(cache.parts[-2:], ("a3s-code", _bootstrap.__version__))
+        self.assertEqual(cache.parts[-3:-1], ("a3s-code", _bootstrap.__version__))
+        self.assertEqual(cache.name, _bootstrap._platform_tag())
 
     def test_xdg_cache_home_honored(self):
         os.environ["XDG_CACHE_HOME"] = "/tmp/xdg-test"
         cache = _bootstrap._cache_root()
-        self.assertEqual(cache, Path(f"/tmp/xdg-test/a3s-code/{_bootstrap.__version__}"))
+        self.assertEqual(
+            cache,
+            Path(
+                f"/tmp/xdg-test/a3s-code/{_bootstrap.__version__}/"
+                f"{_bootstrap._platform_tag()}"
+            ),
+        )
 
     def test_explicit_override_wins(self):
         os.environ["XDG_CACHE_HOME"] = "/tmp/xdg-test"
         os.environ["A3S_CODE_CACHE_DIR"] = "/var/a3s-cache"
         cache = _bootstrap._cache_root()
-        self.assertEqual(cache, Path(f"/var/a3s-cache/{_bootstrap.__version__}"))
+        self.assertEqual(
+            cache,
+            Path(
+                f"/var/a3s-cache/{_bootstrap.__version__}/"
+                f"{_bootstrap._platform_tag()}"
+            ),
+        )
 
 
 class ExtractNativeTests(unittest.TestCase):
@@ -147,11 +209,50 @@ class ExtractNativeTests(unittest.TestCase):
                 _bootstrap._extract_native(buf.getvalue(), Path(tmp) / "pkg")
 
 
+class CachedNativeSelectionTests(unittest.TestCase):
+    def test_selects_exact_interpreter_before_abi3(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cache = Path(tmp)
+            (cache / "_native.abi3.so").write_bytes(b"abi3")
+            (cache / "_native.cpython-312-darwin.so").write_bytes(b"exact")
+            with mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 12)):
+                selected = _bootstrap._find_cached_native(cache)
+            self.assertIsNotNone(selected)
+            self.assertEqual(selected.name, "_native.cpython-312-darwin.so")
+
+    def test_does_not_reuse_another_python_minor(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cache = Path(tmp)
+            (cache / "_native.cpython-313-darwin.so").write_bytes(b"wrong")
+            with mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 14)):
+                self.assertIsNone(_bootstrap._find_cached_native(cache))
+
+    def test_uses_abi3_when_exact_is_absent(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cache = Path(tmp)
+            (cache / "_native.abi3.so").write_bytes(b"abi3")
+            with mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 14)):
+                selected = _bootstrap._find_cached_native(cache)
+            self.assertIsNotNone(selected)
+            self.assertEqual(selected.name, "_native.abi3.so")
+
+
 class EnsureNativeLoadedTests(unittest.TestCase):
     def setUp(self):
         self._tmp = tempfile.mkdtemp(prefix="a3s-bootstrap-test-")
         self._prev_cache = os.environ.get("A3S_CODE_CACHE_DIR")
         os.environ["A3S_CODE_CACHE_DIR"] = self._tmp
+        # The product intentionally rejects CPython < 3.10.  macOS ships a
+        # system Python 3.9 on some runners, though, and these tests exercise
+        # download/cache behavior rather than the version-floor error path.
+        # Run the fixture under a supported simulated minor in that case so
+        # the suite remains useful when invoked with the system interpreter.
+        self._supported_version_patch = None
+        if (sys.version_info.major, sys.version_info.minor) < _bootstrap._MIN_PYTHON:
+            self._supported_version_patch = mock.patch.object(
+                sys, "version_info", _FakeVersionInfo(3, 12)
+            )
+            self._supported_version_patch.start()
         # Reset the module-level latch so each test starts clean.
         _bootstrap._LOADED = False
 
@@ -160,6 +261,8 @@ class EnsureNativeLoadedTests(unittest.TestCase):
             os.environ.pop("A3S_CODE_CACHE_DIR", None)
         else:
             os.environ["A3S_CODE_CACHE_DIR"] = self._prev_cache
+        if self._supported_version_patch is not None:
+            self._supported_version_patch.stop()
         shutil.rmtree(self._tmp, ignore_errors=True)
         _bootstrap._LOADED = False
 
@@ -172,7 +275,7 @@ class EnsureNativeLoadedTests(unittest.TestCase):
                 "version": "3.2.1",
                 "assets": [
                     {
-                        "filename": _bootstrap._wheel_filename("3.2.1"),
+                        "filename": _bootstrap._wheel_candidates("3.2.1")[0],
                         "sha256": expected_sha,
                     }
                 ],
@@ -192,12 +295,15 @@ class EnsureNativeLoadedTests(unittest.TestCase):
         ):
             cache = _bootstrap.ensure_native_loaded("3.2.1")
 
-        # `_cache_root()` keys the cache dir on the module's own __version__,
-        # not the version arg passed to `ensure_native_loaded`. Reference it
-        # directly so this assertion can't go stale on a version bump (the
-        # sibling CacheDirTests follow the same pattern).
-        self.assertEqual(cache, Path(self._tmp) / _bootstrap.__version__)
-        # Native file extracted at cache root, not under a subdirectory.
+        # `_cache_root()` keys the cache dir on the module's own version and
+        # current platform, not the version arg passed to `ensure_native_loaded`.
+        self.assertEqual(
+            cache,
+            Path(self._tmp)
+            / _bootstrap.__version__
+            / _bootstrap._platform_tag(),
+        )
+        # Native file is extracted directly into the platform-scoped cache.
         extracted = list(cache.glob("_native.*"))
         self.assertEqual(len(extracted), 1)
         register_mock.assert_called_once_with(extracted[0])
@@ -209,7 +315,7 @@ class EnsureNativeLoadedTests(unittest.TestCase):
                 "version": "3.2.1",
                 "assets": [
                     {
-                        "filename": _bootstrap._wheel_filename("3.2.1"),
+                        "filename": _bootstrap._wheel_candidates("3.2.1")[0],
                         "sha256": "0" * 64,
                     }
                 ],
@@ -236,7 +342,7 @@ class EnsureNativeLoadedTests(unittest.TestCase):
                 "version": "3.2.1",
                 "assets": [
                     {
-                        "filename": _bootstrap._wheel_filename("3.2.1"),
+                        "filename": _bootstrap._wheel_candidates("3.2.1")[0],
                         "sha256": "0" * 64,
                     }
                 ],
@@ -265,7 +371,7 @@ class EnsureNativeLoadedTests(unittest.TestCase):
                 "version": "3.2.1",
                 "assets": [
                     {
-                        "filename": _bootstrap._wheel_filename("3.2.1"),
+                        "filename": _bootstrap._wheel_candidates("3.2.1")[0],
                         "sha256": hashlib.sha256(wheel_bytes).hexdigest(),
                     }
                 ],
@@ -290,6 +396,76 @@ class EnsureNativeLoadedTests(unittest.TestCase):
             self.assertEqual(call_count["n"], calls_after_first,
                              "second call must not re-download")
 
+    def test_python314_selects_abi3_wheel(self):
+        wheel_bytes = _make_wheel()
+        with mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 14)):
+            abi3_name = _bootstrap._abi3_wheel_filename("3.2.1")
+            manifest = json.dumps(
+                {
+                    "version": "3.2.1",
+                    "assets": [
+                        {
+                            "filename": abi3_name,
+                            "sha256": hashlib.sha256(wheel_bytes).hexdigest(),
+                        }
+                    ],
+                }
+            ).encode()
+
+            calls: list[str] = []
+
+            def fake_get(url: str) -> bytes:
+                calls.append(url)
+                if url.endswith("python-native-manifest.json"):
+                    return manifest
+                return wheel_bytes
+
+            with (
+                mock.patch.object(_bootstrap, "_http_get", side_effect=fake_get),
+                mock.patch.object(_bootstrap, "_register_native") as register_mock,
+            ):
+                _bootstrap.ensure_native_loaded("3.2.1")
+
+        self.assertIn(abi3_name, calls[0])
+        register_mock.assert_called_once()
+
+    def test_python314_falls_back_to_exact_wheel_on_404(self):
+        wheel_bytes = _make_wheel()
+        with mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 14)):
+            abi3_name = _bootstrap._abi3_wheel_filename("3.2.1")
+            exact_name = _bootstrap._wheel_filename("3.2.1")
+            manifest = json.dumps(
+                {
+                    "version": "3.2.1",
+                    "assets": [
+                        {
+                            "filename": exact_name,
+                            "sha256": hashlib.sha256(wheel_bytes).hexdigest(),
+                        }
+                    ],
+                }
+            ).encode()
+
+            calls: list[str] = []
+
+            def fake_get(url: str) -> bytes:
+                calls.append(url)
+                if url.endswith("python-native-manifest.json"):
+                    return manifest
+                if abi3_name in url:
+                    raise _bootstrap.BootstrapHttpError(url, 404)
+                return wheel_bytes
+
+            with (
+                mock.patch.object(_bootstrap, "_http_get", side_effect=fake_get),
+                mock.patch.object(_bootstrap, "_register_native") as register_mock,
+            ):
+                _bootstrap.ensure_native_loaded("3.2.1")
+
+        self.assertIn(abi3_name, calls[0])
+        self.assertIn(exact_name, calls[1])
+        register_mock.assert_called_once()
+
 
 @unittest.skipUnless(
     os.environ.get("A3S_CODE_BOOTSTRAP_LIVE") == "1",
@@ -297,11 +473,12 @@ class EnsureNativeLoadedTests(unittest.TestCase):
 )
 class LiveDownloadTests(unittest.TestCase):
     def test_live_fetch_v3_2_0(self):
-        # 3.2.0 has 12 wheels on GH Release — pick whichever matches the
-        # current runner's platform/interpreter. Skip if the runner isn't
-        # one of the supported triplets.
+        # 3.2.0 has native wheels on GH Release — pick whichever compatible
+        # asset is available for the current runner. Older releases predate
+        # the stable-ABI migration, so a newer interpreter may legitimately
+        # have no matching asset and should be reported as a skip.
         try:
-            _bootstrap._wheel_filename("3.2.0")
+            _bootstrap._wheel_candidates("3.2.0")
         except _bootstrap.BootstrapError as exc:
             self.skipTest(str(exc))
         tmp = Path(tempfile.mkdtemp(prefix="a3s-live-"))
@@ -309,7 +486,10 @@ class LiveDownloadTests(unittest.TestCase):
             os.environ["A3S_CODE_CACHE_DIR"] = str(tmp)
             _bootstrap._LOADED = False
             with mock.patch.object(_bootstrap, "_register_native"):
-                cache = _bootstrap.ensure_native_loaded("3.2.0")
+                try:
+                    cache = _bootstrap.ensure_native_loaded("3.2.0")
+                except _bootstrap.BootstrapError as exc:
+                    self.skipTest(str(exc))
             self.assertTrue(any(cache.glob("_native.*")))
         finally:
             os.environ.pop("A3S_CODE_CACHE_DIR", None)