TypedPython 2: compile @compiled functions through Cython (first part)

[b-re-w]

Refs #23. This is the first part. #23 also requires nbody/spectral-norm ≥ 10× measured alone, and a list of what Cython rejects; both are still open.

Stacked on #19 → #33. The change in this PR is the last commit, ada2fe8.

Feature added

• typedpython.compiled decorator: the identity in CPython. A first-line # typedpython: compiled marks every module-level function.
• compiler.compile_module(path, out) compiles through Cython pure-Python mode to a CPython extension. It refuses any module that fails the gate in compiled mode. The output must give the same results as CPython:
  • float becomes C double.
  • int becomes long long only after an entry range check. Pure functions run with overflow checking, and on overflow the call is redone interpreted, so the result is promoted to an arbitrary-precision int.
  • An argument of a different runtime type sends the call to the interpreted version.
  • list[float] elements are unboxed only when the function cannot turn them into non-floats.
  • math.sqrt keeps its ValueError.
• python -m typedpython demo <module> [args] builds the module, runs main() both interpreted and compiled, prints the timings, and fails unless the output is identical.
• The compile extra adds cython>=3.1 and setuptools.

Test added

• test_compile.py, 10 tests. Before implementation, 6 failed with NotImplementedError (the decorator-identity test passed, since the decorator already existed). The 3 float-list tests were added later; one of them was red until len(xs) was allowed.
• test_cli.py demo tests: 2 red, then 2 green.
• test_compile_measurement.py measures the scalar loop: 136× (277 ms → 2.0 ms) at load 109. Only the ratio means anything.
• Mutation checks: turning overflow checking off makes the promotion test fail; turning the entry guard off makes the big-int test fail.
• A new workflow, .github/workflows/typedpython.yml, runs the Python tests on ubuntu and macOS. Gradle CI never ran them.

Demo (by hand, not a measurement)

I added the module marker to benchmarks/typedpython/py/nbody.py (from #28) and ran demo with 200000 steps. Output was identical: -0.169075164 -0.169083713. Interpreted took 44.8 s and compiled 11.3 s, about 4× faster, at load average 197.

Documentation corrected

• SPEC N-7 (partial)
• design §6.2

Not done

• Methods, default arguments and *args compile as untyped Python.
• List elements are still PyFloat, so every store boxes. The next step is to lower fixed-size arrays to C arrays.
• No measurement on an idle machine yet.

[b-re-w]

Closed: the maintainer dropped the Cython backend (2026-10-03). The reusable parts move to the stage-2 typed IR → C back end in #41: the semantic rules (int promotion through an interpreted redo, entry guards before any effect, exact runtime types, math errors), the demo command, the differential tests, and the TypedPython CI workflow. The branch is kept for reference.