cpython-extensions 1.3.0 release audit
Date: 2026-08-25
Canonical repository: Karvp/cpython-extensions
Live GitHub baseline: main @ 3b55f7b2c35b8ce27a325474ea61b8cf38d99fff

SCOPE
-----
1.3.0 is an implementation release over the live 1.2.0 line. It optimizes all
extension families at their relevant cost centers, adds bounded automatic runtime
qualification at module import, makes explicit auto/live switch selection
plan-aware, expands regression evidence, and changes the current source/release
license to GPL-3.0-only.

The audit preserves historical 1.0.x-1.2.0 release records and benchmark evidence
as historical facts. In particular, previously distributed MPL-2.0 releases are
not retrospectively described as GPL releases.

VERSION / METADATA
------------------
- src/python_extensions/_version.py = 1.3.0
- CITATION.cff = 1.3.0, release date 2026-08-25, GPL-3.0-only
- pyproject license expression = GPL-3.0-only
- target runtime remains CPython >=3.13,<3.14
- runtime dependency remains bytecode>=0.17,<0.18
- optional native extension remains declared by setup.py
- current wheel metadata emits License-Expression: GPL-3.0-only

PUBLIC API
----------
Existing transformation APIs remain compatible. 1.3.0 additionally exports:
- runtime_diagnostics(full=False | True)

Root `import python_extensions` automatically performs the bounded core runtime
qualification before application decorators execute. Exhaustive diagnostics can
be requested with runtime_diagnostics(full=True).

Canonical transformation order remains:
  switch -> partial -> inline -> goto -> specialize/hotpath

`specialize` and `hotpath` remain mutually exclusive final layers.

CROSS-EXTENSION OPTIMIZATION AUDIT
----------------------------------
PASS:
- Shared verification/reporting: bounded weak identity cache and reused CFG data.
- Goto: eliminated duplicate pseudo-statement/exception-table work.
- Inline: skips inapplicable loop/local/exception passes using cheap code-shape
  guards; transformed steady-state code remains unchanged in the V130 control.
- Partial: reuses signature analysis.
- Specialize/hotpath: lower construction/profiling allocation overhead while
  retaining generic fallbacks and bounded state.
- Switch: avoids unnecessary auto AST counting when live selection is impossible,
  and explicit live-threshold auto selection is plan-aware.
- Native live: no speculative hot-path rewrite was accepted without evidence;
  the already-qualified fused dispatcher remains intact.

A proposed more aggressive switch location-metadata shortcut was rejected after
six structural regressions demonstrated a CPython CFG/code-shape change. The
release therefore keeps the verified metadata rewrite rather than accepting a
microbenchmark-only optimization.

RUNTIME QUALIFICATION AUDIT
---------------------------
PASS. The new runtime layer:
- executes package-owned synthetic code only;
- checks the supported CPython 3.13 implementation boundary at root import;
- verifies wordcode alignment, required opcodes, CodeType.replace,
  exception-table decoding, shared verifier, and lightweight switch/goto
  prerequisites;
- caches successful and failed core qualification exactly once;
- stores detached failure metadata instead of retaining traceback frames;
- keeps bytecode/inline/specialization/live destructive checks lazy;
- exposes a detached diagnostic dictionary;
- avoids unsupported live/native probing on free-threaded builds;
- has dedicated regression coverage for concurrency, caching, repeated access,
  failure caching, and weak retention.

CORRECTNESS / STRESS
--------------------
PASS on CPython 3.13.5:
- native-enabled pytest: 458/458
- native-enabled pytest under -X dev, PYTHONMALLOC=debug, -W error: 458/458
  (third-party pytest plugin autoload disabled for an isolated package-owned run)
- source-only pytest with optional native extension absent: 448 passed, 1 skip
- specialization adversarial full: 8,316,000 calls
- live-switch compatibility full: 1,239,100 calls
- runtime_diagnostics(full=True): all certified subsystems PASS
- installed host-wheel smoke: PASS

BENCHMARK EVIDENCE
------------------
PASS. User-facing performance evidence is ordered by decision stage.

PRIMARY — NORMAL PYTHON VS EXTENSION SUPPORT:
BENCHMARK_PRIMARY_V130.{json,md} validates all routes/misses and measures three
fresh CPython 3.13.5 processes. The headline is an intended 1,024-way source
router rather than a tiny crossover case:
- integer routes: 7624.5 ns if/elif, 8137.7 ns match, 51.8 ns dict.get,
  57.0 ns extension = 133.7x vs if/elif and 142.7x vs match;
- string routes: 4906.0 ns if/elif, 5180.2 ns match, 61.8 ns dict.get,
  69.0 ns extension = 71.1x vs if/elif and 75.1x vs match.

The bound dict.get control is deliberately adjacent to the headline so the large
speedups are scoped to linear source-level dispatch. The extension is within
roughly 10-12% of the hand-built hash-table control on this host while keeping
case-oriented source and the extension verifier/reporting contract.

The same primary suite records 59.9 -> 46.1 ns (1.33x) for an ordinary affine
helper call vs frozen inline and 4333.0 -> 1652.4 ns (2.67x) for an explicit
three-state Python dispatcher vs strict goto. A natural structured-loop control
is retained at 1772.0 ns rather than being omitted.

The retained V110 scaling control remains useful for crossover behavior from
small route counts through 1,024 cases; it is no longer needed to supply the
headline large-router result because V130 now measures that workload directly.

SECONDARY — EXTENSION MODES / BACKENDS:
The retained V122 live matrix remains the workload-selection evidence for
portable, ctypes live, and native live. Native live can materially outperform
portable on repeated in-frame VM/parser routing, but retained HTTP/direct/sparse
controls show ties or portable wins. These numbers are not used as the headline
normal-Python-vs-extension claim.

TERTIARY — 1.2 TO 1.3 IMPLEMENTATION OVERHEAD:
BENCHMARK_OPTIMIZATION_V130.{json,md} records three fresh processes per version
and separates construction/profiling measurements from transformed steady-state
controls. Median construction improvements are approximately 1.15x goto, 1.13x
switch auto, 1.24x inline, 1.07x partial, and 1.18x explicit specialize; hotpath
wrapper construction is approximately unchanged and active profiling is 1.94x
faster.

Root import is intentionally about 1.12x slower because of automatic bounded
qualification. Representative steady-state transformed co_code fingerprints are
byte-identical across the 1.2/1.3 comparison for all measured extension families,
so short-run steady timing deltas are not marketed as code-generation speedups.

DOCUMENTATION
-------------
PASS: current README, CHANGELOG, architecture, compatibility, comprehensive guide,
live-switch guide, specialization guide, runtime-diagnostics guide, security,
contributor/setup/release guidance, benchmark guide, issue/PR metadata, citation,
and repository metadata are synchronized to the 1.3.0 contract.

Historical RELEASE_HISTORY and 1.0.x-1.2.0 certification/audit sections remain
historical records rather than current API/license authority.

PACKAGING / RELEASE TOOLING
---------------------------
PASS on the certification Linux/CPython 3.13.5 host for the source/backend gates:
- optional C extension builds and imports;
- two builds with fixed SOURCE_DATE_EPOCH=1787538817 produced byte-identical
  host-native wheels and canonical sdists;
- exact host wheel installation/smoke passed;
- wheel METADATA emits GPL-3.0-only and includes LICENSE.

The generic host `linux_x86_64` wheel is not publishable to PyPI. The tagged
workflow still requires cibuildwheel/manylinux repair from the exact canonical
sdist, two-build wheel equality, explicit raw-linux-wheel rejection, checksum
verification, exact manylinux wheel smoke, exact-sdist testing, and stable-only
protected OIDC publication.

Local Twine/trove-classifiers execution is not claimed because those optional
packages are absent in this execution environment. GitHub Actions remains the
publication authority for those gates.

LICENSE TRANSITION
------------------
PASS for repository consistency: the current 1.3.0 source line is
GPL-3.0-only across LICENSE, pyproject, CFF, repository metadata, contributor
terms, and generated package metadata. Historical MPL-2.0 grants remain described
as historical grants and are not revoked or rewritten by this source update.

AUDIT RESULT
------------
PASS as a 1.3.0 source/release candidate for CPython 3.13.5 within the documented
support boundary. Do not treat this audit as evidence that PyPI publication has
already occurred. Final release requires a clean immutable v1.3.0 tag and green
GitHub Actions release gates.
