Plan: Define maturin and PyO3 validation contracts

[leynos]

Summary

This branch adds a design document for maturin and PyO3 validation because Rust-extension template renders need an explicit packaging contract before implementation work changes generated tests, CI, and release workflows. The design is captured in docs/maturin-pyo3-validation-design.md and is based on the observed approaches in Prosidy Darn, Cuprum, TEI Rapporteur, Stilyagi, and femtologging, plus upstream maturin, PyO3, and wheel-specification guidance.

It also repairs the generated Rust act-validation path that surfaced on this pull request: template/.github/workflows/ci.yml.jinja now points rust-cache at rust_extension, template/{% if use_rust %}rust_extension{% endif %}/Cargo.toml.jinja now uses PyO3 0.29.0, and tests/helpers/ci_contracts.py asserts the cache workspace contract.

There is no linked issue, roadmap task, or execplan for this branch. This is primarily a design branch that authorizes the next implementation pass, with a narrow generated-CI repair needed to keep the branch green.

Review walkthrough

• Start with docs/maturin-pyo3-validation-design.md for the problem statement, evidence table, goals, and non-goals.
• Review docs/maturin-pyo3-validation-design.md for the three-layer contract: pin agreement, active-toolchain validation, and wheel artefact checks.
• Check docs/maturin-pyo3-validation-design.md for version canonicalisation, pin-surface rules, and the maturin/PyO3 comparison contract.
• Then inspect docs/maturin-pyo3-validation-design.md for the local wheel-build contract, skip semantics, focused assertions, and snapshot drift rules.
• Review template/.github/workflows/ci.yml.jinja and tests/helpers/ci_contracts.py for the generated Rust cache workspace fix.
• Finish with docs/maturin-pyo3-validation-design.md for CI and release routing, failure modes, verification strategy, implementation sequence, and open decisions.

Validation

• make check-fmt: passed
• make lint: passed
• make typecheck: passed
• make test: passed, 32 passed, 2 skipped, 3 snapshots passed
• make test WITH_ACT=1: passed, 32 passed, 2 xfailed, 3 snapshots passed
• git diff --check: passed

Notes

The design deliberately keeps pure-Python renders free of maturin, PyO3, Cargo, and wheel-action dependencies. It also treats femtologging as a negative case by requiring future template tests to reject broad maturin ranges and bare maturin develop validation as sufficient upgrade coverage.

The act-specific fix addresses two generated Rust workflow failures observed while validating this pull request: rust-cache running cargo metadata from a directory without Cargo.toml, and cargo audit rejecting PyO3 0.28.3 for RUSTSEC-2026-0176 and RUSTSEC-2026-0177.

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1bef9990-76ca-4872-a98a-03469a5deb61

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch maturin-validation

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}