[qartik]

Stacked on #17; this PR should merge after it. Because #17's rust branch is
in a fork, the base is an upstream mirror of its current head. After #17
merges, retarget this PR to main and remove codex-pr17-rust-base.

Summary

• generate _native.pyi from the PyO3 declarations during development and CI
• fail CI when the committed generated stub is stale, and package it in release wheels
• preserve the legacy val_fns class attribute through introspectable PyO3 declarations
• document the supported Rust surface and enforce public-item documentation
• codify the QIR i64 boundary for Python inputs, including malformed out-of-range values
• make the Python compatibility suite an explicit permanent release gate
• verify Cargo.toml and pyproject.toml versions stay aligned

Validation

• CI=true uv run src/scripts/ci_checks.sh
• cargo test --no-default-features
• generated the stub on Linux with Maturin 1.15
• built a stripped wheel and verified that it contains the checked generated stub

PyO3 still labels binary introspection experimental. Maturin also removes the
introspection section when stripping Linux binaries, so CI generates and checks
the stub before release builds; release wheels remain stripped and package that
checked stub.

The larger streaming-output and formatter-architecture changes remain separate follow-ups.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-23T16:33:13.085231Z	dc27c62	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[qartik]

this file is now auto-generated.

[Copilot]

Copilot review overview

🟡 Changes recommended

The CI stale-stub check does not detect when the generated stub is absent from the committed tree.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Stale-stub gate ignores untracked missing generated files · New

What changed in this PR

Codifies Python/Rust formatter contracts, generated bindings, release packaging, and compatibility requirements.

Changes:

• Generates and validates PyO3 stubs.
• Documents Rust APIs and enforces version alignment.
• Tests Python compatibility and signed 64-bit boundaries.

File	Description
.github/​workflows/​release.yml	Builds stripped release wheels.
Cargo.toml	Enables PyO3 introspection.
README.md	Documents contracts and stub generation.
pyproject.toml	Adds Maturin tooling configuration.
src/​labeled_formatter.rs	Documents the public Rust API.
src/​lib.rs	Documents exports and checks versions.
src/​python.rs	Exposes introspectable binding metadata.
src/​qir_formatter/​_native.pyi	Updates the generated native stub.
src/​scripts/​ci_checks.sh	Generates and validates the stub.
tests/​README.md	Defines compatibility-suite expectations.
tests/​test_public_api.py	Tests the legacy validator registry.
tests/​test_qir_formatter.py	Tests signed 64-bit boundaries.
uv.lock	Locks the Maturin dependency.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟢 Approval recommended

The API, generation, packaging, and boundary changes are consistent and adequately validated.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Stale-stub gate ignores untracked missing generated files