# CPython compatibility

The current checkpoint runs a statically linked AArch64 musl CPython 3.12.13
in both the native host and Chromium Worker, plus a dynamically linked native
acceptance fixture. Generated runtime and standard
library artifacts stay under the repository's ignored `.tmp/cpython-3.12.13`
directory.

## Verified behavior

- Startup and version reporting from the ordinary CPython executable.
- Source-based standard-library bootstrap, including `encodings`.
- Multi-file programs under `/project`.
- Filesystem-backed package discovery and imports.
- A separately packaged pure-Python project image installed over the runtime
  snapshot.
- A separately packaged, checksum-pinned `packaging` 26.2 wheel installed as a
  second overlay, imported from the guest filesystem, and accompanied by its
  original distribution metadata.
- Unhandled exceptions with readable guest file paths, source lines, exception
  type, message, and exit status 1.
- Identical project image and script behavior in the native CLI and Chromium.
- Dynamic `libpython3.12.so` loading through the guest musl interpreter.
- CPython's normal `dlopen` import of the `_struct` native extension, including
  its relocations against both `libpython` and guest libc.

The regression project is in `guest-tests/cpython/project`. It imports
`phase5pkg.calculator` and `packaging`, prints `multi-file result: 42`, verifies
the installed wheel's version and `METADATA` file, then raises a deliberate
`RuntimeError`. One bounded guest run therefore covers project and third-party
package discovery, source loading, package data, and traceback formatting.

## Packaging and execution

`binarrow image pack --guest-root /project/phase5 ...` creates the project
image. Browser hosts install it through the existing project-image operation.
Native hosts can apply the same image over a base snapshot with the repeatable
`--filesystem-install <image>` run option.

`guest-tests/cpython/package-packaging.sh` downloads the official pure-Python
wheel into `.tmp`, verifies its pinned SHA-256 digest, retains the wheel's
package and distribution metadata layout, and creates a separate installable
image. It does not install anything into the host Python environment.

Use these end-to-end verifiers after `guest-tests/cpython/build.sh`:

```sh
guest-tests/cpython/verify.sh
guest-tests/cpython/verify-browser.sh
guest-tests/cpython/build-dynamic.sh
guest-tests/cpython/verify-dynamic.sh
```

Both scripts set `TMPDIR` and all build caches beneath the repository's `.tmp`
directory. The browser test is opt-in because the generated artifacts are
about 76 MiB and the guest run currently takes several minutes.

## Current limitations

- The dynamic checkpoint deliberately packages only `_struct`; broad standard
  library extension coverage and third-party native wheels are not claimed.
- Guest-side `pip`, dependency resolution, and package-index access are not
  implemented. Hosts can checksum-pin and package compatible pure-Python wheels
  as deterministic installable images; `packaging` 26.2 is the verified
  checkpoint.
- Threaded Python execution is not supported by the single-threaded guest
  runtime.
- Socket-backed package indexes and native wheels are outside the current
  browser service surface.
- Translation covers a scalar Tier-1 subset; unsupported CPython blocks fall
  back to the interpreter by code identity.