Investigate Python 3.15 support

[pschanely]

Python 3.15 is now in beta (3.15.0b3 as of June 2026), so it's time to start evaluating what CrossHair needs in order to support it. CrossHair is unusually sensitive to CPython minor-version changes because it (a) intercepts bytecode opcodes and (b) ships a C extension (crosshair/_tracers.c) that pokes at interpreter internals, so each new minor version tends to require a porting pass.

This is a tracking issue to scope the work. Areas to evaluate:

• C tracer opcode table (crosshair/_tracers.c) — version-gated PY_VERSION_HEX branches for the set of intercepted opcodes.
• Python-side opcode interception (crosshair/opcode_intercept.py, crosshair/tracers.py) — check_opcode_support() and the version gates around CALL/BUILD_MAP/etc.
• C API surface in _tracers.c vs. APIs removed/deprecated in 3.15.
• stdlib libimpl/ patches that gate on sys.version_info and may need a >= (3, 15) arm.
• CI / packaging — add 3.15 to the test matrix and trove classifiers (currently capped at 3.13 in pyproject.toml, though code already handles 3.14).
• Dependencies — confirm z3-solver and other deps publish 3.15 wheels.

Initial evaluation to follow in a comment.

[pschanely]

Initial evaluation (code audit @ d7ac86f, against Python 3.15.0b3)

1. C tracer opcode table — the main gap 🔴

crosshair/_tracers.c builds its intercepted-opcode table with version arms that stop at 3.14:

#if   PY_VERSION_HEX < 0x030D0000   // <= 3.12
    [FORMAT_VALUE] = 1, [BINARY_SUBSCR] = 1,
#elif PY_VERSION_HEX < 0x030E0000   // == 3.13
    [CALL_KW] = 1, [CONVERT_VALUE] = 1, [BINARY_SUBSCR] = 1,
#elif PY_VERSION_HEX < 0x030F0000   // == 3.14
    [CALL_KW] = 1, [CONVERT_VALUE] = 1, [LOAD_COMMON_CONSTANT] = 1,
#endif

On 3.15 (PY_VERSION_HEX >= 0x030F0000) none of these arms apply, so CALL_KW, CONVERT_VALUE, LOAD_COMMON_CONSTANT, etc. drop out of the table. That feeds directly into check_opcode_support() in crosshair/tracers.py:93, which raises for any required-but-unsupported opcode on 3.12+:

raise TraceException(f"The C-level tracer does not support these opcodes: ...")

Likely fix: add a #elif PY_VERSION_HEX < 0x03100000 (3.16) arm, after confirming 3.15's CALL/subscript opcode set. The 3.15 beta whatsnew documents no new/removed/renamed bytecode instructions vs 3.14 so far, so this may be as simple as extending the 3.14 arm to also cover 3.15 — but that needs verification against dis on a real 3.15 build (the adaptive-interpreter specializations are the usual surprise).

2. C API surface — clean ✅

3.15 removes several deprecated C APIs (PyWeakref_GetObject/PyWeakref_GET_OBJECT, PyUnicode_AsDecoded/EncodedObject/Unicode, PyImport_ImportModuleNoBlock, PySys_ResetWarnOptions, Py_GetPath/Py_GetPrefix/…) and soft-deprecates _PyBytes_Resize / PyBytes_FromStringAndSize(NULL, len). I grepped _tracers.c for all of these: the only nearby symbol is PyUnicode_AsEncodedString (line 397), which is not on the removal list. So no C-API porting appears necessary for the extension.

3. Python-side version gates — needs a sweep 🟡

sys.version_info gates already extend to 3.14 in several places (builtinslib.py:4332, collectionslib.py:129/260, copyext.py). The relevant boundary checks to re-examine for 3.15:

• crosshair/opcode_intercept.py:587/591 (>= (3, 12), >= (3, 14) arms)
• crosshair/tracers.py:94/282
• _tracers_test.py:93/107 skip-conditions are written as >= (3, 14) — these will silently keep skipping on 3.15 and should be revisited so coverage doesn't quietly lapse.

No >= (3, 15)-specific behavior is anticipated yet, but each gate should be checked rather than assumed.

4. CI / packaging 🟡

• pyproject.toml requires-python = ">=3.8" and classifiers stop at 3.13, even though 3.14 is handled in code — classifiers are stale and should be refreshed alongside this.
• CI currently pins 3.13 for docs/hypothesis jobs; the test matrix needs a 3.15 entry (initially allow-failure while porting).

5. Dependencies 🟡

Confirm z3-solver publishes 3.15 wheels before adding 3.15 to CI as a hard requirement (z3 wheel lag has historically blocked new-version support).

---

Suggested next steps

1. Build a 3.15.0b3 venv and run the suite to capture the first concrete failure (expect the check_opcode_support TraceException first).
2. Diff dis.hasarg/opcode names between 3.14 and 3.15 to confirm the C-tracer arm can simply be extended.
3. Add the < 0x03100000 arm in _tracers.c, refresh the >= (3, 14) test skips, and update classifiers/CI.

Biggest unknown: whether 3.15's adaptive-interpreter specializations introduce intercept-relevant opcode forms not visible in the prose whatsnew — that requires a real build to settle. I don't have a 3.15 interpreter in this environment (running 3.11), so step 1 needs a 3.15 build to proceed.

Sources: What's new in Python 3.15 · whatsnew/3.15.rst

---

Generated by Claude Code

[pschanely]

Update: fix implemented and verified on a real 3.15.0b3 build

Pushed to branch claude/review-prioritize-issues-7afpzq (commit be6b28b).

The fix

The C tracer's intercepted-opcode table (_ch_TRACABLE_INSTRUCTIONS in crosshair/_tracers.c) had PY_VERSION_HEX arms only through 3.14 (< 0x030F0000). On 3.15 none matched, so CALL_KW/CONVERT_VALUE/LOAD_COMMON_CONSTANT dropped out of the table and check_opcode_support() raised a TraceException at import. Those opcodes are unchanged in 3.15 (confirmed: CALL_KW=53, CONVERT_VALUE=56, LOAD_COMMON_CONSTANT=80 in 3.15's opcode_ids.h), so the fix just extends the arm to < 0x03100000. Also added a 3.15 allow-failure CI job and refreshed the trove classifiers (pyproject.toml had lagged at 3.13).

Verification (built CPython 3.15.0b3 from source)

• C extension compiles cleanly against 3.15.0b3 headers — zero warnings, so the version-gated internal-struct code (most of it gated >= 3.14) is fine on 3.15.
• Bug reproduced pre-fix: compiling the current main _tracers.c against 3.15 → CALL_KW reports supported=False → check_opcode_support(_CALL_OPCODES) raises TraceException. So main is genuinely broken on 3.15 today.
• Post-fix: check_opcode_support passes; import crosshair.tracers succeeds.
• Test suites pass: _tracers_test.py + opcode_intercept_test.py → 18 passed, 3 skipped (the skips are the intentional 3.12/3.13-only stack-depth tests).
• End-to-end works: crosshair check on a buggy contract correctly found the counterexample —

  demo.py:3: error: false when calling clip(-1) (which returns -1)
  

  exercising the full pipeline (tracer → opcode interception → Z3 → counterexample) on 3.15.

Notes for full CI

• z3-solver is NOT a blocker — it ships as py3-none-manylinux (ABI-agnostic); z3-solver==4.16.0.0 installs fine on 3.15. Base pip install -e . succeeds.
• One dev-only snag: the [dev] extra pins numpy==2.3.3, which has no 3.15 wheel yet and falls back to a (slow) source build. This only affects the dev/test extra, not CrossHair itself — but it's why the 3.15 CI job is marked allow-failure for now. Worth loosening the numpy pin (or marking it ; python_version < "3.15") once a 3.15 numpy wheel lands.

Remaining (not blocking 3.15)

The other audit items still hold: sweep is done for the opcode path; no C-API porting needed. The only follow-up I'd track separately is the numpy dev-pin above.

---

Generated by Claude Code

[pschanely]

Full test suite run on Python 3.15.0b3

Ran the complete suite as CI does (CROSSHAIR_EXTRA_ASSERTS=1 PYTHONHASHSEED=0 pytest -n auto --dist worksteal crosshair) against the from-source 3.15.0b3 build:

25 failed, 10570 passed, 12 skipped, 1 xfailed in 587s (9m47s)

So ~99.8% passes, but — as expected — stdlib changes in 3.15 broke several libimpl reimplementations. Breakdown (one already fixed, one is a local artifact):

✅ Fixed (pushed, commit 9c9abbb)

• unicode_categories (1 failure) — 3.15 ships Unicode 17.0.0; the per-version category-range cache lacked a "17.0.0" key → KeyError. Runtime was already correct (falls back to computing live), so this just restores the startup cache. Regenerated the entry on 3.15 and verified the test passes.

➖ Not a real issue (local env)

• main_test::test_mypycrosshair_command — fails only because I didn't install mypy in the throwaway venv ("Unable to find mypy; skipping"). Will pass in CI.

🔴 Real 3.15 regressions remaining — 23 failures in 4 areas

1. struct error-message format (7): _pack_into + patch-equivalence
3.15 reworded the buffer TypeError: "argument must be read-write bytes-like object, not int" → "pack_into() argument 2 must be read-write bytes-like object, not int". CrossHair hardcodes the old message in structlib.py:163, so it diverges from native and structlib_test's regex no longer matches. Fix: version-gate the message (and the test). Low difficulty, slightly tedious.

2. re / relib (6): lookahead, nongreedy, match repr, sliced string, greedy backtracking
Root cause is the new 3.15 re internals — re.match now routes through the new prefixmatch (re/__init__.py:166), and that path reaches CrossHair's symbolic strings without interception:
TypeError: expected string or bytes-like object, got 'LazyIntSymbolicStr'. Fix: teach relib about 3.15's prefixmatch/match path. Medium-deep — touches the regex engine integration.

3. decimal / decimallib (7): create_decimal_from_float, precision, patch-equivalence
3.15's _pydecimal.py changed create_decimal_from_float/_fix/as_tuple internals; CrossHair's Decimal.__new__ (decimallib.py:327/405) no longer round-trips them: TypeError: Cannot convert (0, 44468, -4) to Decimal and int() argument ... not 'LazyIntSymbolicStr'. Fix: re-sync decimallib with 3.15's _pydecimal. Medium-deep.

4. deepcopy patch-equivalence (3): re.Pattern, latin-1 codec, builtin add
Likely downstream of the re/codec internal changes (copying a compiled pattern / codec result differs). Worth re-checking after the re fix lands — some may resolve for free.

Recommendation

The struct one is a quick, safe fix I can do now. The re and decimal ones are real reimplementation-sync work with design choices (how the symbolic engine should hook 3.15's new prefixmatch path; how closely to track _pydecimal internals). I'd value your steer on scope before diving in — see the question I'll post on the PR/chat.

Everything passing on 3.15 except these 4 areas is a strong baseline — the core engine, tracer, and the other ~25 stdlib modules are clean on 3.15.

---

Generated by Claude Code

[pschanely]

Fixed the stdlib-driven 3.15 failures (pushed)

Worked through the 24 real failures. 17 are fixed; the remaining 7 are a build artifact of my test environment, not 3.15 regressions — details below. Re-ran all previously-failing files on 3.15.0b3: only the 7 Decimal-artifact cases remain.

Fixed (commits 9c9abbb, e2018c6, 156fabb)

• struct (7) — 3.15's pack_into now validates the minimum argument count before parsing the format string, and reworded the wrong-buffer message to "pack_into() argument 2 must be read-write bytes-like object, not int". Mirrored both (version-gated) in structlib._pack_into.
• re (6) — the module-level re.match is now an alias of the new re.prefixmatch and dispatches through Pattern.prefixmatch (a new method). CrossHair only patched Pattern.match, so symbolic strings reached the unpatched C method. Now registers Pattern.prefixmatch with the same symbolic impl.
• copy.deepcopy (3) — 3.15 dropped the private _nil parameter (signature is now (x, memo=None)), so a 3-positional call raises TypeError. Version-gated the _deepcopy patch signature to match.
• unicodedata (1) — already fixed in 9c9abbb (Unicode 17.0.0 cache).

The remaining 7 Decimal failures are a _decimal-less build artifact ⚠️

My from-source 3.15.0b3 build has no C _decimal — 3.15 defaults to --with-system-libmpdec=yes and no system libmpdec was available (egress-blocked), so decimal fell back to pure-Python _pydecimal. Official 3.15 builds (and actions/setup-python in CI) ship C _decimal.

Evidence this is the cause, not a 3.15 change:

• Every failing path routes through real _pydecimal.py (e.g. __add__/_fix/create_decimal_from_float), which only runs when C _decimal is absent. The malformed value (0, 44468, -4) is a 3.15 _pydecimal._WorkRep (confirmed via its __repr__) reaching CrossHair's Decimal.__new__.
• The native Decimal differs purely by backend, not version. Decimal(1, 2): C (3.11) → TypeError: optional argument must be a context; pure-Python (my 3.15 build) → Decimal('1'). Decimal([(1,2),(3,4)]): C → "argument must be a sequence of length 3"; pure-Python → "Invalid tuple size...". So patch_equivalence is comparing CrossHair against the wrong (pure-Python) native.

I deliberately did not patch decimallib for these — making a 5,500-line vendored _pydecimal reimplementation chase pure-Python-only behavior would be wrong work and risks real regressions. Recommend confirming these 7 pass on an official 3.15 build with C _decimal (they should). If you'd like, I can add a CI step that asserts _decimal is present so this never silently regresses.

Net result on 3.15.0b3

Full suite was 25 failed / 10570 passed. After these fixes: all 17 genuine failures resolved; the 7 Decimal cases are environmental (C _decimal absent) and 1 earlier mypy failure was also just my venv (mypy not installed). The core engine + ~27 other stdlib modules are clean on 3.15.

---

Generated by Claude Code