feat(coverage): add bounded PyO3 peer-evidence gate

[seonghobae]

Buyer-visible blocker

Central OpenCode coverage currently fails before pytest collection in mature maturin/PyO3 packages when the isolated source-only sandbox cannot import the compiled native extension. This leaves otherwise verified Python-only product PRs blocked even when the exact head passes repository Python, Rust/PyO3, package, GPU, and fuzz jobs.

This bounded slice

• add scripts/ci/python_native_extension_peer_gate.py;
• require exact maturin + PyO3 metadata and the declared dotted module-name;
• classify only complete pytest collection failures caused exclusively by that declared native module being absent;
• reject mixed imports, test failures, setup/teardown errors, pytest internal errors, crashes, truncation, malformed input, and unsafe paths;
• refuse deferral when Rust, Cargo, native crate, native stub, packaging, dependency lock, requirements, GitHub workflow/action, or maturin metadata changes;
• verify trusted CheckRun records by exact head SHA, workflow, check name, completed state, and success conclusion;
• reject pending, failed, stale-head, status-only, lookalike, missing, duplicate-requirement, or malformed evidence;
• add APA 7 doctoring and authoritative changelog material.

Verification

Focused local verification on the published source:

81 tests passed
220/220 production statements covered
98/98 production branches covered
Python compilation succeeded

The tests include the exact fast_mlsirm._core failure shape and adversarial native-boundary, filesystem, log, metadata, and check-evidence cases.

Security boundary

This PR does not skip tests, build a PR-selected extension, enable network access, add a Python compatibility stub, approve a pull request, or weaken branch protection. A successful classification is explicitly not passing evidence; the final central workflow must still prove trusted exact-head Python, Rust/PyO3, and package checks.

Remaining integration

Keep this PR Draft. A follow-up commit in this PR must wire the helper into the central coverage and approval workflow, add the permanent workflow contracts, and re-run fast-mlsirm#546 on its exact current head. Until that integration is reviewed, the current fail-closed coverage behavior remains authoritative.

Advances #784.

[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: CHILL

Plan: Pro Plus

Run ID: afdd2045-a975-4694-b3fb-b1716b7a75fe

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

---

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

[seonghobae]

@opencode-agent address

Integrate the published PyO3 native-extension helper into the protected central OpenCode coverage/review path on this same branch; keep the PR Draft until the integration is complete and exact-head evidence passes.

Mirror the existing fail-closed R peer-evidence pattern rather than creating a second privileged reviewer. Required behavior:

1. In .github/workflows/opencode-review-dispatch.yml, capture each Python pytest/coverage command's complete bounded log and exit status without changing successful behavior.
2. When and only when a Python suite fails, invoke scripts/ci/python_native_extension_peer_gate.py classify-pytest against the exact log, the relevant regular non-symlink pyproject.toml, and the exact base-to-head changed-file list.
3. A successful classification must not be reported as ordinary passing coverage. Publish a distinct compact marker stating that source-only Python collection was deferred exclusively for the unchanged declared PyO3 module and requires exact-head native peer evidence.
4. In the trusted review/approval phase, query live CheckRun objects for the exact PR head and verify the repository-owned Python, Rust/PyO3, and package checks with require-checks. Do not accept statuses, stale heads, queued/cancelled/skipped checks, name lookalikes, duplicate requirements, or predecessor evidence. Preserve the existing R peer gate and all normal failure paths.
5. Approval must remain blocked if the classifier, changed-file trust boundary, check inventory, or required peer check is absent or malformed. The classifier is a deferral classifier, never approval evidence by itself.
6. Add permanent workflow-contract tests covering: pure declared-module collection failure; mixed missing imports; test/setup/teardown/internal/crash/truncated failures; native/Cargo/Rust/stub/packaging/lock/requirements/workflow changes; exact-head successful peer checks; stale/pending/failed/status/lookalike evidence; coexistence with R deferral; coverage summary wording; and approval-gate enforcement.
7. Include the helper and workflow contract tests in permanent Python 3.10/3.14, compilation, 100% production statement/branch coverage, and public-docstring gates. No temporary repair workflow, branch-selected privileged execution, Python compatibility stub, networked PR test, skipped test, synthesized approval, merge, release, or protection change may remain.
8. After exact-head central checks pass, rerun OpenCode/Noema review for unchanged fast-mlsirm heads build(deps): bump cloudflare/wrangler-action from 3.15.0 to 4.0.0 #546 d111e2b1341b0daab6b813074c7a7dbcf5c24ff4, fix(deps): protobuf를 aiplatform 호환 범위로 유지 #549 12fc519ca798c8400840f04b3b19c07754ad7dfe, and build(deps): bump google-cloud-bigquery from 3.42.0 to 3.42.2 #550 8db4c235d466446429fc32bdeeef3ca1fdaa8827; do not reuse their failed source-only coverage verdicts.

Update the doctoring and CHANGELOG to distinguish source-only measurement, trusted native peer evidence, and remaining interpretation limits. Preserve immutable called-workflow source, reviewer credentials, NVIDIA/OpenCode model policy, independent approval, unresolved-thread, and branch-protection boundaries.

[seonghobae]

@jules Implement the remaining central workflow integration on this existing Draft PR. Preserve the published helper and fail-closed trust boundary; do not create another PR or temporary workflow.

Required scope:

• wire python_native_extension_peer_gate.py classify-pytest into .github/workflows/opencode-review-dispatch.yml only after a real bounded Python suite failure, using the exact pytest log, regular non-symlink pyproject, and exact base-to-head changed-file list;
• publish a distinct PyO3 deferral marker rather than ordinary passing coverage;
• in the trusted approval phase, query live exact-head CheckRun records and call require-checks for protected Python, Rust/PyO3, and package peer checks;
• reject stale/pending/failed/status/lookalike/missing/malformed evidence and preserve the existing R deferral independently;
• add permanent workflow-contract tests for classification, changed-boundary rejection, exact-head peer evidence, R/PyO3 coexistence, summary wording, and approval enforcement;
• include the helper and workflow integration in Python 3.10/3.14 compile, 100% statement/branch coverage, public docstrings, actionlint, security, and changelog/doctoring checks.

Do not build PR-selected native code in the central sandbox, add a compatibility stub, skip product tests, use networked PR execution, change reviewer tokens or NVIDIA/OpenCode policy, weaken approval/protection gates, mark Ready, merge, or release. Commit as normal descendants without force-push, and report exact verification commands and the final head SHA.

[seonghobae]

@jules Implement the remaining integration directly on this branch; do not create any temporary, self-modifying, encoded-patch, or branch-writing workflow.

Required GREEN slice:

1. Wire scripts/ci/python_native_extension_peer_gate.py into .github/workflows/opencode-review-dispatch.yml after the isolated pytest attempt has produced a complete bounded log and exact changed-file inventory.
2. Accept deferral only when classify-pytest proves the sole failure is the exact declared maturin/PyO3 module and require-checks proves trusted exact-head CI::python, CI::rust, and CI::package CheckRuns are completed/successful.
3. Treat classification as deferred peer evidence, never as a passing test; preserve all coverage/docstring gates for the Python-owned changed files and fail closed on mixed failures, native/package/lock/workflow changes, stale or status-only evidence.
4. Add permanent workflow-contract tests covering ordering, trusted workflow/check-name ownership, exact-head binding, malformed evidence, and the fast_mlsirm._core case.
5. Run the focused suite, complete central tests, 100% production statement/branch/docstring evidence, compilation, and exact-head security workflows. Keep Draft until all current-head evidence is GREEN.

After integration, rerun OpenCode review for unchanged fast-mlsirm PRs #546, #549, and #550; predecessor coverage failures are not reusable.

[seonghobae]

@jules Integrate the committed helper into the central opencode-review-dispatch.yml now; keep this PR Draft until end-to-end exact-head evidence is complete.

Required fail-closed flow:

1. Preserve the current central source-only coverage run and capture its complete bounded combined stdout/stderr plus exit status. On success, continue unchanged.
2. On failure, write the exact base…head changed-file list to a bounded newline file and invoke python_native_extension_peer_gate.py classify-pytest. Deferral is allowed only when that helper proves the sole failure is absence of the exact unchanged maturin/PyO3 module-name; any native/Cargo/stub/packaging/lock/requirements/workflow/maturin-metadata change or mixed pytest failure remains blocking.
3. A successful classification is not a pass. Query CheckRun—not StatusContext—evidence for the exact PR head and invoke require-checks for these exact fast-mlsirm CI jobs before the central review may treat source-only coverage as peer-proven:
   • CI::python
   • CI::rust
   • CI::package
   • CI::gpu-smoke
   • CI::fuzz
     Keep Security Scan and SAST under the existing central gates. Reject absent, pending, failed, stale-head, lookalike-workflow, duplicate-requirement, or malformed evidence.
4. Emit an explicit non-success classification such as coverage_deferred_to_exact_head_native_peer_evidence; do not report the source-only sandbox as passing and do not lower the repository's 100% coverage contract.
5. Add workflow contract tests that exercise the exact fast_mlsirm._core collection failure, successful exact-head peer evidence, stale/pending/failed/status-only/check-name/workflow-name mismatches, native-boundary changes, mixed failures, truncation, and normal pure-Python pytest failures.
6. Re-run the central workflow against current exact heads of fast-mlsirm#546, #549, and #550. The integration is accepted only if those previously blocked Python-only PRs receive no coverage CHANGES_REQUESTED, while a synthetic native-code change and mixed pytest failure still block.

Do not build PR-selected native code inside the central sandbox, introduce a Python stub, auto-approve, weaken required checks, use COPILOT_GITHUB_TOKEN, or disturb the existing reviewer-agent secret contract. Update APA 7 doctoring and the authoritative changelog after GREEN.

[seonghobae]

@coderabbitai Review the current Draft head 68e8b1695280d11c58b5553457442527f9d0542c specifically as an implementation-design review for the remaining PyO3 workflow integration. Do not approve, mutate, or merge. Identify the exact existing R-deferral variables/functions/approval gates in .github/workflows/opencode-review-dispatch.yml, and provide a minimal patch plan that reuses them for python_native_extension_peer_gate.py while preserving ordinary Python failures, exact-head CheckRun validation, R/PyO3 coexistence, and all immutable-source/credential boundaries. Flag any defect in the published helper or tests before integration.

[coderabbitai]

Rate Limit Exceeded

@seonghobae have exceeded the limit for the number of chat messages per hour. Please wait 5 minutes and 1 seconds before sending another message.

[seonghobae]

@opencode-agent

Prepare the next bounded integration only after .github#759 produces a GREEN exact head, because both changes touch the authoritative coverage workflow and stale-base integration would reintroduce or overwrite the LLVM runtime-boundary repair.

For the eventual current-main integration:

• invoke python_native_extension_peer_gate.py classify-pytest only after a real pytest collection failure has been captured completely and before converting that failure into deferred peer-evidence requirements;
• write changed paths from the exact base/head diff into a bounded regular file;
• require the declared maturin/PyO3 module and refuse deferral for every native, packaging, dependency, workflow, stub, or metadata change already covered by the helper;
• query CheckRun evidence from trusted GitHub metadata and require exact current head plus repository-owned Python, Rust/PyO3, and package checks, all completed/successful; statuses, stale heads, duplicates, lookalikes, and missing evidence remain blocking;
• keep classification explicitly non-passing until peer checks are proven;
• add permanent workflow-ordering, permission, exact-head, and fail-closed contracts; execute/cover/compile the helper through the exact-head quality lane;
• rerun fast-mlsirm#546 only after the central integration merges.

Keep Draft. Do not mutate the authoritative workflow from the pre-#759 base, approve, or merge.

[seonghobae]

@jules Implement the existing TDD RED workflow contracts on exact live head 5bc9ba4070866934ed819c2ff06f209b785d7b88 as normal descendant commits. Keep this PR Draft. Do not amend, rebase, force-push, create a repair workflow, mark Ready, merge, release, change branch protection, change reviewer credentials, or alter NVIDIA/OpenCode model policy.

Precondition: before every write, re-read the live head and stop without mutation unless it is the expected current head or your own direct descendant.

Coverage integration

In .github/workflows/opencode-review-dispatch.yml, preserve the existing sandbox, run_and_capture, R deferral, immutable-source, credential, and publication boundaries. Add a separate Python-suite runner that uses the identical timeout --kill-after=20 900 setpriv ... low-privilege environment but retains the complete bounded log long enough to classify a real nonzero Python suite exit.

Initialize exactly:

python_native_peer_check_required=0

Only after a Python configured/default pytest/coverage command actually fails:

1. snapshot changed_files_for_coverage to a bounded regular file;
2. require the relevant ${project_dir}/pyproject.toml to be regular and non-symlink;
3. invoke the trusted helper:

python3 "$GITHUB_WORKSPACE/scripts/ci/python_native_extension_peer_gate.py" classify-pytest \
  --log "$log_file" \
  --pyproject "$project_dir/pyproject.toml" \
  --changed-files "$changed_files_file" \
  --repo-root "$COVERAGE_SOURCE_WORKDIR"

4. on classifier success, do not report ordinary PASS and do not increment failures; emit a distinct section containing all these literal contracts:

### Python native-extension source-only deferral
- Result: DEFERRED
the unchanged declared PyO3 module was unavailable in the source-only sandbox
exact-head Python, Rust/PyO3, and package CheckRuns

and set python_native_peer_check_required=1;
5. on classifier rejection, retain the ordinary exact exit failure and increment failures;
6. any other Python suite failure in the same run remains blocking.

In the compact PASS decision, when the variable is 1, emit exactly:

- Python native-extension peer evidence: deferred source-only collection requires successful exact-head peer checks

Do not build/install PR-selected native code, add a Python stub, skip tests, or grant network access.

Approval integration

Mirror—but do not replace—the existing R peer-check pattern. Add independent functions that:

• detect only the exact compact Python deferral marker;
• query the live PR statusCheckRollup immediately before approval and normalize only CheckRun nodes with __typename, workflow name, check name, exact trusted $HEAD_SHA, status, and conclusion into a bounded JSON file;
• call:

python3 "$GITHUB_WORKSPACE/scripts/ci/python_native_extension_peer_gate.py" require-checks \
  --checks-json "$checks_file" \
  --head-sha "$HEAD_SHA" \
  --required-check "CI::python" \
  --required-check "CI::rust" \
  --required-check "CI::package"

• reject missing, pending, failed, skipped, cancelled, stale, status-only, lookalike, malformed, or lookup-failed evidence.

Call this gate in both approval paths that already call require_r_cmd_check_for_deferred_coverage: the deterministic model-unavailable blocker path and the normal APPROVE path. R and PyO3 deferrals must coexist independently. On failure, leave review state unchanged with a bounded WAITING_FOR_PYTHON_NATIVE_PEER_CHECKS explanation; never synthesize approval.

Permanent tests and verification

Make the current tests GREEN without weakening them:

python -m pytest -q \
  tests/test_python_native_extension_peer_gate.py \
  tests/test_python_native_extension_peer_gate_nested_project.py \
  tests/test_python_native_extension_peer_gate_workflow_contract.py

Then run the permanent Python 3.10/3.14 quality workflow, focused and complete 100% production statement/branch coverage, interrogate 100%, compileall, actionlint, full central tests, security and supply-chain checks. Fix actual failures only. Preserve CHANGELOG.md and docs/doctoring/python-native-extension-peer-evidence.md; update them only where integration semantics or verified limitations changed.

After GREEN, report the exact final SHA and verification commands in a PR comment. Do not request approval or change Draft state.

[seonghobae]

Exact-head quality run 31133025300 confirms the intended integration RED: 87 focused tests passed and only the three workflow-contract tests failed because opencode-review-dispatch.yml still lacks python_native_peer_check_required, the distinct source-only deferral summary, and trusted require-checks enforcement. Python 3.10 compatibility passed; all security workflows passed.

@jules Implement the central workflow integration now rather than weakening these tests. Preserve the existing R peer gate and privileged reviewer chain. After GREEN, run full central coverage/docstrings/actionlint and replay OpenCode review against exact fast-mlsirm heads #546, #549, and #550.

[seonghobae]

@opencode-agent address

Fix the exact current-head quality failure on 5bc9ba4070866934ed819c2ff06f209b785d7b88 by completing the integration already required by this Draft PR; do not weaken or delete the three failing workflow-contract tests.

Run 31133025300, job 92726135563, proves 87/90 focused tests pass and these exact contracts remain RED:

1. python_native_peer_check_required=0 and the bounded classify-pytest invocation are absent from .github/workflows/opencode-review-dispatch.yml;
2. the coverage artifact lacks the distinct ### Python native-extension source-only deferral, - Result: DEFERRED, and exact-head peer-check requirement text;
3. the approval phase does not yet call require-checks for CI::python, CI::rust, and CI::package against PR_HEAD_SHA using live GraphQL CheckRun evidence.

Implement the documented fail-closed flow:

• initialize python_native_peer_check_required=0 and keep ordinary source-test failure authoritative;
• only after a real Python pytest failure, call scripts/ci/python_native_extension_peer_gate.py classify-pytest with the bounded pytest log, changed-file list, --repo-root "$COVERAGE_SOURCE_WORKDIR", and exact --pyproject "$project_dir/pyproject.toml";
• if and only if that classifier succeeds, serialize a distinct DEFERRED section, never PASS, stating the unchanged declared PyO3 module was unavailable in the source-only sandbox and that exact-head Python, Rust/PyO3, and package CheckRuns are mandatory;
• pass this state into the trusted approval job;
• query current live check runs, preserve __typename, require actual CheckRun values, and call the helper's require-checks for CI::python, CI::rust, and CI::package with --head-sha "$PR_HEAD_SHA";
• retain R CMD check deferral logic independently;
• reject mixed failures, changed native/package/workflow boundaries, missing/pending/failed/stale/status-only/lookalike evidence, malformed metadata, or any classifier error;
• keep all source handling read-only and bounded, no PR-selected build/install, no Python native stub, no token weakening, no approval or merge inside the helper.

After GREEN, run all 90 focused tests at 100% statement/branch coverage, the complete central suite, interrogate 100%, compileall, actionlint, Python 3.10 compatibility, security workflows, and exact-head review. Keep Draft, needs-revision, do-not-merge, and no auto-merge until integration and a live fast-mlsirm proof run are complete.

[seonghobae]

@jules Implement the missing production integration on current branch fix/pyo3-native-peer-gate; do not create a separate workflow-only substitute. Wire scripts/ci/python_native_extension_peer_gate.py into .github/workflows/opencode-review-dispatch.yml after the isolated pytest log and exact changed-file inventory exist. Deferral must remain non-PASS evidence and require exact-head successful trusted CheckRuns CI::python, CI::rust, and CI::package; preserve all Python coverage/docstring gates and the independent R peer gate; fail closed on mixed/native/package/lock/workflow changes or malformed/stale/status-only evidence. Add permanent ordering/ownership/exact-head workflow-contract tests, run focused/full quality and security, and keep Draft.

[seonghobae]

@opencode-agent address

Implement the committed workflow-integration RED contract on this Draft branch. Do not weaken the helper or tests. Preserve the existing R peer gate and reviewer credential chain.

The central coverage job must capture bounded combined pytest output and status, classify only the exact unchanged maturin/PyO3 module-absence collection failure, then require trusted exact-head CheckRun success for CI::python, CI::rust, CI::package, CI::gpu-smoke, and CI::fuzz. StatusContext, stale heads, lookalike workflow/check names, pending/failed/missing/malformed evidence, native-boundary changes, and mixed failures remain blocking. Emit an explicit non-success source-only deferral classification; never call it passing, never build PR-selected native code, and never auto-approve.

After GREEN, run the permanent workflow contracts, full central coverage/docstrings/actionlint/security, then replay exact current heads of fast-mlsirm #546, #549, and #550.

[seonghobae]

@opencode-agent address

A new RED trust-boundary contract is committed at 9878fe3e9db6b35d8d7274595d996b80f5faaad2. _touches_native_or_trust_boundary() currently catches requirements-ci.txt but misses direct children such as requirements/ci.txt, requirements/ci.in, and nested-service .../requirements/package.txt. Implement the minimal GREEN rule: when a safe changed path's parent directory is named requirements, direct .txt and .in children must block native peer deferral; unrelated .txt files outside that directory must remain eligible. Keep all existing lock, native, package, workflow, exact-head, and mixed-failure gates. Include the new file in 100% added-production coverage/compilation and the permanent central workflow integration. Keep Draft.

[seonghobae]

@jules Apply and remove the committed one-shot patcher scripts/ci/apply_pyo3_peer_gate_workflow_integration.py on the current branch, then run the exact verification below and commit the resulting ordinary source changes. Do not force-push, mark Ready, merge, or weaken tests.

python3 scripts/ci/apply_pyo3_peer_gate_workflow_integration.py
rm scripts/ci/apply_pyo3_peer_gate_workflow_integration.py
python3 -m coverage erase
python3 -m coverage run --branch -m pytest -q \
  tests/test_python_native_extension_peer_gate.py \
  tests/test_python_native_extension_peer_gate_nested_project.py \
  tests/test_python_native_extension_peer_gate_workflow_contract.py
python3 -m coverage report \
  --include=scripts/ci/python_native_extension_peer_gate.py \
  --show-missing --fail-under=100
python3 -m pytest -q \
  tests/test_opencode_agent_contract.py \
  tests/test_repository_branch_coverage_review_schedulers.py
python3 -m compileall -q \
  scripts/ci/python_native_extension_peer_gate.py \
  tests/test_python_native_extension_peer_gate.py \
  tests/test_python_native_extension_peer_gate_nested_project.py \
  tests/test_python_native_extension_peer_gate_workflow_contract.py

The reviewed local proof is 91 focused tests and 100% helper statement/branch coverage. The patch also removes the temporary source-snapshot workflow and the duplicate quality workflow. Keep only python-native-extension-peer-gate-quality-ci.yml, then run its actionlint/complete-suite gates on the pushed exact head.

[seonghobae]

@opencode-agent address

The branch now contains scripts/ci/apply_pyo3_peer_gate_workflow_integration.py, which is only an intermediate patch plan and is not an accepted product artifact. Apply its reviewed transformations as ordinary commits to .github/workflows/opencode-review-dispatch.yml, permanent workflow-contract tests, doctoring, and CHANGELOG; correct any integration defects found by the real suites; then delete the patcher itself. Keep tests/test_python_native_extension_peer_gate_requirements_directory.py GREEN by making direct .txt/.in children of a directory named requirements block deferral. Do not add a branch-writing workflow, trigger, compatibility stub, skipped tests, or duplicated reviewer. Run actionlint, focused/full Python 3.10/3.14, 100% production statement/branch coverage, docstrings, security/supply-chain, and keep Draft.