Skip to content

ci: qualify CPython 3.14 and bound interpreter support - #1134

Merged
Brad-Edwards merged 4 commits into
devfrom
GOV-901-python-314-qualification
Aug 14, 2026
Merged

ci: qualify CPython 3.14 and bound interpreter support#1134
Brad-Edwards merged 4 commits into
devfrom
GOV-901-python-314-qualification

Conversation

@doublewhy

@doublewhy doublewhy commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

Plain-language summary

  • Context: OpenRAE publishes a Python package and needs an explicit, tested interpreter range.
  • Problem: Package metadata admitted untested future Python versions, normal CI exercised only Python 3.12, and the MCP tests used event-loop behavior removed in Python 3.14.
  • Fix: Qualify standard CPython 3.11–3.14 end to end, preview free-threaded 3.14 separately, reject Python 3.15 for now, and harden the compatibility runner.

Issues closed

Closes #1097

Closes #1117

Closes #1100

This is the complete successor to the partial work in #1087 and #1089. It does not edit or close either earlier PR.

Support boundary

  • Supported standard interpreters: CPython 3.11, 3.12, 3.13, and 3.14.
  • Preview signal only: free-threaded CPython 3.14 (3.14t), scheduled/manual and continue-on-error.
  • Not admitted: Python 3.15. A separate post-final dependency and wheel qualification is required before raising the upper bound.

The standard matrix is blocking within the CI workflow: its jobs do not use continue-on-error. Adding its dynamic matrix contexts to protected-branch required checks is an administrator setting outside this PR; this PR does not claim that setting is already configured.

The compatibility session fails closed unless the selected runtime matches the named CPython feature release and threading mode. It restores the matrix selector into Nox's command environment, performs a frozen all-extras sync, runs the hermetic suite, builds one wheel and one source distribution, installs the wheel into a new environment, checks installed Requires-Python, imports every public package, and smokes raes --version plus raes --help.

The MCP dependency remains on the qualified 1.x API line (>=1.28.1,<2) so an unreviewed future major release cannot silently invalidate this compatibility result.

Verification

The branch was merged with dev at 944b4617, retaining the merged #1129 CLI traceability and this PR's #1097/#1100/#1117 traceability. The merged head also combines #1130's Python 3.11.4 OCI extraction floor, #1143's branch-aware coverage policy, and this PR's standard CPython 3.11-3.14 and below-3.15 support boundary.

Local results across the two rebases, with the affected suite, MCP checks, Ruff, and policy graph rerun after the final README resolution:

  • Final 3e26db12 head, standard CPython 3.14 affected focused suite: 261 passed and 1 deselected.
  • Immediately preceding rebased head, standard CPython 3.11, 3.12, 3.13, and 3.14 plus free-threaded 3.14 focused matrix: 261 passed and 1 deselected per interpreter.
  • Immediately preceding rebased head, full standard CPython 3.14 compatibility session: 6,608 passed and 1 skipped; exact-runtime assertion, wheel/sdist build, clean install, metadata/import validation, and installed CLI smoke all passed.
  • MCP deprecation-to-error regression: 85 passed.
  • Final local docs graph passed Vale with zero findings, executable quickstart tests, warning-as-error Sphinx HTML, and output inventory validation.
  • Ruff 0.15.9 check and formatting validation passed for all changed Python/tooling files.
  • Repository policy, requirement-diff policy, semantic/assurance/authority/deprecation governance, and ADR immutability checks passed. The optional remote Ground Control requirement lookup was unavailable due local DNS and was skipped by its existing offline policy.

Earlier isolated Ubuntu 24.04 qualification established the complete cross-version path before this rebase:

Runtime Exact build Hermetic suite Build/install/import/CLI
CPython 3.11 3.11.15 6,426 passed, 1 skipped passed
CPython 3.12 3.12.3 6,426 passed, 1 skipped passed
CPython 3.13 3.13.14 6,426 passed, 1 skipped passed
CPython 3.14 3.14.6, GIL enabled 6,426 passed, 1 skipped passed
CPython 3.14t 3.14.6, GIL disabled 6,426 passed, 1 skipped passed

The updated exact head eabc4b0052b0c03162a7151330f7bd752f0728bd, merged with dev at 944b4617, passed hosted verification: canonical verification passed in 10m14s; the required CPython 3.11, 3.12, 3.13, and 3.14 compatibility jobs passed; Sonar passed in 2m20s; and CodeQL, docs, fuzz, supply-chain, container integration, GitGuardian, and title policy passed.

Scope boundary

No SDL, contract, runtime, evaluator, solver, or backend semantics change. No Python 3.15 production or preview claim is introduced.

Qualify standard CPython 3.11 through 3.14 with exact-runtime, frozen-suite, distribution-build, clean-install, metadata, import, and CLI checks. Add a non-advisory workflow matrix and a separate nonblocking 3.14t preview, while bounding installation below 3.15. Harden MCP test loop ownership and Nox option parsing as required by the qualification graph.

Closes #1097

Closes #1117

Closes #1100
@doublewhy
doublewhy force-pushed the GOV-901-python-314-qualification branch from 3ef2748 to 3e26db1 Compare August 13, 2026 03:29
@doublewhy
doublewhy marked this pull request as ready for review August 13, 2026 03:41
@doublewhy
doublewhy marked this pull request as draft August 13, 2026 08:00
@OpenRAE OpenRAE deleted a comment from doublewhy Aug 13, 2026
@Brad-Edwards
Brad-Edwards marked this pull request as ready for review August 14, 2026 00:23
@Brad-Edwards

Brad-Edwards commented Aug 14, 2026

Copy link
Copy Markdown
Collaborator

Updated the branch to current dev and completed the verification-policy integration:

  • Merged dev at 944b4617; the test-file conflict was resolved by retaining both the Python-compatibility tests and the branch-aware coverage tests.
  • Amended and re-pinned ADR-014 to define the supported-interpreter matrix as a required CI extension to the single-interpreter verify gate. The historical-identity digest was refreshed because it content-binds the ADR index.
  • Added the CPython 3.11, 3.12, 3.13, and 3.14 compatibility checks to branch protection for both dev and main.
  • Local completion verification passed: 6,935 unit tests, 59 integration tests, contracts, policy, Ruff, proof replay, documentation, and combined coverage.
  • Hosted verification passed on eabc4b00: all four required interpreter jobs, canonical verify, Sonar, CodeQL, documentation, fuzz, supply-chain, container integration, GitGuardian, and title policy.

@Brad-Edwards
Brad-Edwards merged commit 876df88 into dev Aug 14, 2026
17 checks passed
@Brad-Edwards
Brad-Edwards deleted the GOV-901-python-314-qualification branch August 14, 2026 16:40
Brad-Edwards added a commit that referenced this pull request Sep 2, 2026
…alyzer (#1160)

* ci(sonar): clear mechanical tool violations and exempt false positives

The dev branch sonar job has been red since tools/ became a Sonar source
root (#54) under the raes-strict gate (#527): branch analysis reports 215
new-code violations while PR analysis only scans changed lines. This slice
removes every mechanical violation in tools/ and exempts the three false
positives driving the security rating.

Code fixes, all behavior-preserving (each checker emits identical output
and exit status on this repo before and after):

- parameterize bare generic annotations (S6543/S6538/S6540/S6542),
  using dict[str, object] for parsed JSON/YAML payloads
- extract duplicated string literals into module constants (S1192),
  following the existing _SEMANTIC/_DANGLING idiom in the parity checker
- drop exception classes already covered by a caught base class (S5713):
  HTTPError/URLError/TimeoutError under OSError, JSONDecodeError under
  ValueError
- classify markdown link targets by scheme prefix (http:) instead of
  protocol literal (S5332), and collapse chained startswith calls (S8513)
- make _is_sequence a TypeGuard so flow analysis understands the
  iteration that follows it (S5864)
- restructure nested conditional expressions (S3358), remove a dead
  if/pass wrapper (S108), drop an unused unpack target (S1481) and an
  unused parameter (S1172), move trailing comments (S139), use a dict
  literal (S7498), fix noqa comment syntax (S7632), and wrap two
  overlong lines

sonar-project.properties exemptions, each with recorded justification:

- e6: S5443 on tools/isabelle_tool.py - the /tmp literal is a private
  bubblewrap tmpfs target inside the proof sandbox
- e7: S1309 - the repo lint contract requires justified noqa
  suppressions, so tracking each as a violation conflicts with policy
- e8: S1313 on tools/real-daemon/ - authored RFC-1918 lab addresses in
  the hardware smoke scenario

Closes #1152

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(sonar): respect the proof-evidence and identity digest pins

The first commit's cosmetic edits to tools/isabelle_tool.py invalidated the
participant-opacity proof evidence manifest, which digest-pins that file's
exact bytes, and the sonar-project.properties edit invalidated the
identity-cutover registry's classified content digest.

- revert tools/isabelle_tool.py to its pinned bytes and exempt its two
  residual style findings in sonar-project.properties instead (e9: S5713,
  e10: S7632), with the pin recorded as justification
- reclassify sonar-project.properties in
  tools/policy/historical_identity_records.json with its new content
  digest; the retained retired-identity occurrence count is unchanged

Verification: nox -s tests green (includes the opacity-proof and
identity-cutover policy suites), tools/check_repo_policy.py pass.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(tools): decompose oversized governance checkers into support packages

The three checkers that predate the 500-line policy carried the remaining
structural Sonar violations on dev (S104 file length, S138 function
length, cyclomatic/cognitive complexity up to 70/66, S1142 return counts,
S107 parameter counts). Each is now an import-stable entry point over a
support package of focused modules, all under the 500-line cap:

- tools/check_sdl_catalog_parity.py (2,039 lines) ->
  tools/sdl_catalog_parity/ (paths, expectation registry split at section
  boundaries with a merged-registry overlap guard, table rows, expected
  classifications, typed-model traversal, checks)
- tools/check_specification_coverage.py (1,640 lines) ->
  tools/specification_coverage/ (keys, primitives, protocol, concepts,
  artifacts, snapshot, analysis)
- tools/check_formal_semantic_validation.py (3,121 lines) ->
  tools/formal_semantic_validation/ (types, shape, replay, claims,
  protocol, corpus, snapshot, analysis, loading, releases, baseline,
  retest, production, satisfiability, supplement loading)

Mega-functions are decomposed into single-responsibility helpers under
the thresholds (complexity <= 10, <= 100 lines, <= 3 returns, <= 7
parameters); the two 8-parameter snapshot validators now take frozen
scope dataclasses. Pure restructuring: no validation rule changes.

Test updates: the three monkeypatch sites that patched replay_case,
load_bounded_json_object, and subprocess.run through the old monolithic
module now patch the consumer modules, preserving what each test proves
(the no-replay-of-historical-evidence guarantee now pins both consumer
modules).

Verification: each checker produces identical output and exit status on
this repo before and after (the formal checker's full offline integrity
and replay pass included); nox -s tests green (7,005+ tests incl. the
80-test formal-validation suite and 25-test parity suite); ruff format
and lint clean; tools/check_repo_policy.py pass.

Closes #1154

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci(sonar): exclude hardware-only smoke scripts from coverage measurement

tools/real-daemon/ scripts run only against a real libvirtd/QEMU host,
so the hermetic CI coverage report can never execute their lines; the
mechanical type-hint edits there were dragging new-code coverage below
the 80% gate. Exclude the directory from coverage measurement only (it
stays fully analyzed for issues) and reclassify the properties file's
identity digest.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(tools): finish the strict-gate polish on the split checkers

The PR quality-gate scan counted 22 residual findings on the new
support-package code (Sonar's complexity counter is stricter than the
hand-estimates, moved-but-unchanged functions count as new code, and
its flow analysis does not honor TypeGuard narrowing):

- inline the sequence isinstance-narrowing where iteration follows a
  guard (S5864), and annotate Sequence parameters where callers
  already guarantee it
- decompose the remaining over-threshold functions: markdown table
  parsing, internal-link scanning, model-field alias walking, field
  classification, source/request/concept entry checks, stage outcome
  vs classification coupling, occurrence entries, corpus polarity
  coverage, the retest observation sweep, and the satisfiability head
- parameterize the last bare list annotations (S6543) and reduce
  _pointer_step to three exits (S1142)
- split prose-level checks out of sdl_catalog_parity._checks to stay
  under the 500-line cap

All three checkers still emit byte-identical output on this repo;
nox -s tests and check_repo_policy pass; ruff clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(tools): split the last two over-threshold validators

Sonar counts the eight-term snapshot-binding or-chain and the
concept-results sweep loop above the complexity threshold; hoist the
binding predicate and the sweep into named helpers. Checker output
remains byte-identical; tests and policy pass.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci(sonar): declare the qualified 3.13 and 3.14 interpreters to the analyzer

sonar.python.version still said 3.11-3.12 after CI qualified CPython
3.13 and 3.14 (#1134), so the strictest gate analyzed the code with
3.12-era rules. Declare the full supported range; the 3.11 floor keeps
newer-syntax suggestions gated on the lint contract. The properties
file's identity digest is reclassified accordingly.

Note for the merge: the next dev branch scan may surface findings the
newer-interpreter rules detect on existing code; they would appear on
the dev analysis, not on this PR's changed-line scan.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Brad Edwards <j.bradley.edwards@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants