python_extensions / cpython-extensions 1.3.0
RELEASE CERTIFICATION
Date: 2026-08-25
Canonical repository: https://github.com/Karvp/cpython-extensions
Baseline GitHub main commit: 3b55f7b2c35b8ce27a325474ea61b8cf38d99fff
Target runtime: CPython >=3.13,<3.14
Certified runtime used here: CPython 3.13.5
License: GPL-3.0-only

STATUS
------
PASS for the documented 1.3.0 source/release-candidate tree on the certified
CPython 3.13.5 host. Publication remains subject to the immutable tagged GitHub
Actions release gates, including manylinux repair, metadata/Twine validation,
and the protected PyPI Trusted Publishing environment.

1.3.0 is an optimization, runtime-qualification, and licensing release. It keeps
the established 1.2 transformed hot-path semantics while reducing construction
and adaptive-profiling overhead, making CPython runtime assumptions executable,
and relicensing the current source/release line under GPL-3.0-only. Historical
1.0.x through 1.2.0 release records retain their original MPL-2.0 grants.

CORRECTNESS GATES
-----------------
- Complete pytest suite with the native extension available: 458 passed.
- Complete suite under CPython -X dev, PYTHONMALLOC=debug, warnings-as-errors,
  fixed PYTHONHASHSEED, native extension available: 458 passed. Third-party pytest
  plugin autoload was disabled so unrelated environment plugin warnings could not
  invalidate the package-owned warnings-as-errors run.
- Source-only suite with the optional native extension deliberately absent:
  448 passed, 1 native-only test skipped as designed.
- Exhaustive package-owned runtime diagnostics: PASS for portable switch,
  live layout, native live, goto, inline, specialization, shared verifier,
  exception-table decoding, CodeType.replace, and bytecode 0.17.0.
- Installed host-wheel smoke: PASS (native live + specialization + inline + goto).
- Python compileall over src/tests/tools/benchmarks/scripts: PASS.

RUNTIME QUALIFICATION
---------------------
Version 1.3.0 introduces src/python_extensions/_runtime.py. Root package import
runs one bounded, cached core qualification suite before decorators can rewrite
application functions. The import-time suite executes package-owned synthetic
code only and verifies:
- CPython implementation and the 3.13.x support boundary;
- wordcode/instruction alignment and required opcodes;
- CodeType.replace stability;
- exception-table decoding;
- the shared CFG/stack verifier;
- lightweight switch/goto runtime prerequisites.

Historically lazy or mutation-sensitive checks remain deferred to first use or
runtime_diagnostics(full=True): portable switch compile/execute, live writable
layout, optional native dispatcher, bytecode dependency, inline decoding, and
specialization execution. Probe results and failures are cached as detached
state; the runtime tests cover once-only execution, concurrency, repeated access,
failed-probe caching, and weak-retention behavior. Free-threaded builds avoid the
unsupported live/native probe path rather than silently changing GIL behavior.

STRESS / DIFFERENTIAL GATES
---------------------------
Both inherited full-scale harnesses were rerun on the exact 1.3.0 implementation:
- Specialization v121 adversarial full harness:
    8,316,000 differential/stress calls passed
  Run with PYTHONMALLOC=debug, CPython -X dev, warnings as errors, and a fixed
  PYTHONHASHSEED.
- Live-switch v18.2 compatibility full harness:
    1,239,100 calls passed
  Run with PYTHONMALLOC=debug, CPython -X dev, warnings as errors, and a fixed
  PYTHONHASHSEED.

PERFORMANCE EVIDENCE
--------------------
The certification presents benchmark evidence in three levels so adoption
benefits are not conflated with mode/backend or version-to-version improvements.

1. PRIMARY: NORMAL PYTHON VS EXTENSION SUPPORT

Committed current-release evidence:
  benchmarks/results/BENCHMARK_PRIMARY_V130.json
  benchmarks/results/BENCHMARK_PRIMARY_V130.md
  benchmarks/scripts/benchmark_primary_v130.py

The primary driver uses intended workloads and three fresh CPython 3.13.5
processes. Its headline is a 1,024-way source-level router. Every route and miss
is validated before timing; successful timing traffic is uniform over all routes
in deterministic scrambled order. Median per-dispatch results are:

- 1,024 integer routes:
    if/elif 7624.5 ns; match 8137.7 ns; bound dict.get 51.8 ns;
    extension switch 57.0 ns
    = 133.7x vs if/elif and 142.7x vs match
- 1,024 string routes:
    if/elif 4906.0 ns; match 5180.2 ns; bound dict.get 61.8 ns;
    extension switch 69.0 ns
    = 71.1x vs if/elif and 75.1x vs match

The bound dictionary is an explicit fairness control. The headline result is a
large advantage over linear source-level dispatch, not a claim that the
extension beats Python hash tables by two orders of magnitude. On the certified
host the extension is within about 10-12% of the hand-built dict.get control
while preserving declarative case source, verification, and transformation
reporting. Executable co_code for the 1,024-case direct-value extension remains
74 bytes versus 17,420/19,466 bytes for the integer if/elif/match controls; route
table object memory is not included in that bytecode-size comparison.

The same primary suite records:
- ordinary affine helper call vs frozen inline:
    59.9 ns -> 46.1 ns, 1.33x
- explicit three-state Python dispatcher vs strict goto:
    4333.0 ns -> 1652.4 ns, 2.67x
  with a naturally structured loop control at 1772.0 ns.

Goto is therefore measured on the explicit/generated state-machine workload it
is intended to replace, while the structured control remains visible so the
result is not generalized to every naturally structured loop.

The retained V110 2-1,024-route matrix remains a crossover/scaling control. It
shows that small switches may be near or below the crossover while direct-value
extension dispatch remains dictionary-class as linear if/elif/match cost grows.

2. SECONDARY: EXTENSION MODES / BACKENDS

The 1.2.0 V122 live workload matrix is retained unchanged for portable-vs-live
workload selection. It is mode-selection evidence, not the primary adoption
benchmark. The matrix includes positive and negative controls: native live reaches
about 2.47x over portable in the recorded 2,048-route dense-VM case, while HTTP
routing is approximately tied and direct/template-friendly workloads can favor
portable.

3. RELEASE-TO-RELEASE IMPLEMENTATION IMPROVEMENTS

Committed evidence:
  benchmarks/results/BENCHMARK_OPTIMIZATION_V130.json
  benchmarks/results/BENCHMARK_OPTIMIZATION_V130.md
  benchmarks/scripts/benchmark_optimization_v130.py

V130 is an engineering evidence identifier for the 1.3.0 optimization pass. The
comparison uses three fresh processes per implementation and separates
construction/profiling cost from steady-state generated code.

Representative median construction improvements versus the live 1.2.0 baseline:
- goto:                1.15x
- switch auto:         1.13x
- inline:              1.24x
- partial:             1.07x
- explicit specialize: 1.18x
- hotpath wrapper construction: approximately unchanged
- active hotpath pre-promotion profiling: 1.94x faster

Fresh root-package import increased from 11.73 ms to 13.14 ms (1.12x) because
1.3.0 performs bounded automatic interpreter qualification. The design was
explicitly refined to keep heavier live/inline/specialization probes lazy.

Representative steady-state transformed co_code fingerprints are byte-identical
between 1.2.0 and 1.3.0 for goto, portable/native switch, inline, partial,
explicit specialization, and promoted hotpath. Short timing movement on those
controls is therefore treated as measurement noise rather than a generated-code
speed claim.

IMPLEMENTATION OPTIMIZATIONS
----------------------------
- Shared verifier results use a bounded identity/weakref cache; the cache avoids
  CodeType hashing/equality and does not retain transformed code objects.
- Transformation reporting reuses verifier/CFG analysis instead of rebuilding it.
- Goto reuses pseudo-statement scans and exception-table decoding.
- partial() reuses signature analysis through binding and transformed signature
  construction.
- Inline skips loop-only, local-slot, and exception-table passes when code shape
  proves they cannot contribute.
- Monomorphic hotpath profiling uses scalar current-shape/count state and direct
  one-constant/one-type paths instead of repeated aggregate allocations.
- switch(mode="auto", live_threshold=...) is plan-aware: compact direct-value,
  expression-template, and statement-template portable plans veto live mutation;
  the already-analyzed portable plan is reused when portable wins.
- A more aggressive switch source-location shortcut was rejected after structural
  tests showed it changed CPython CFG shape and disabled an existing optimization.

PACKAGING / REPRODUCIBILITY
---------------------------
The final source declares the optional _livegate C extension through setup.py and
ships its source in the sdist. On the certification host, two independent builds
with SOURCE_DATE_EPOCH=1787538817 produced byte-identical host-native wheels and
byte-identical canonical sdists. The host-native wheel is an internal validation
artifact; it carries the generic linux_x86_64 tag and is not a PyPI Linux payload.

Built wheel metadata records:
- Metadata-Version: 2.4
- Name: cpython-extensions
- Version: 1.3.0
- License-Expression: GPL-3.0-only
- Requires-Python: >=3.13,<3.14
- License file included under .dist-info/licenses/LICENSE

The exact host wheel was installed into an isolated target and passed
 tools/smoke_release.py. Tagged Linux publication still requires cibuildwheel to
build/repair the exact canonical sdist into a manylinux x86-64 wheel twice and
requires byte-identical output before staging. Raw linux_x86_64 wheels remain
explicitly rejected from GitHub Release and PyPI.

METADATA / PUBLICATION GATES
----------------------------
This execution environment does not have the optional local Twine,
trove-classifiers, or build frontend packages installed, so local `twine check`
and `tools/check_metadata.py` are not represented as PASS here. Setuptools backend
builds and generated wheel metadata were inspected directly. The tagged GitHub
workflow retains mandatory metadata validation and Twine checks before release.

LICENSING
---------
The current source and 1.3.0 release are GPL-3.0-only. pyproject.toml,
CITATION.cff, repository metadata, README/contributor documentation, generated
wheel metadata, and the canonical LICENSE file are synchronized to that SPDX
expression. Historical release records are intentionally not rewritten to imply
that already-distributed MPL-2.0 versions were originally GPL-licensed.

FINAL ASSESSMENT
----------------
The 1.3.0 release-candidate implementation is correctness-, stress-, runtime-,
optimization-, packaging-, and licensing-qualified on CPython 3.13.5 within the
documented support boundary. Final public publication requires a green immutable
v1.3.0 GitHub Actions run, including manylinux, metadata/Twine, checksum, exact
artifact smoke, GitHub Release, and protected PyPI gates.
