fix(coverage): gate PyO3 test deferral on exact-head native peer checks

[seonghobae]

Buyer-visible blocker

The central OpenCode coverage sandbox cannot currently review Python changes in a mature PyO3/maturin package when the package's native extension is required during pytest collection. The sandbox correctly runs with no network and does not execute PR-selected build/install hooks. As a result, ContextualWisdomLab/fast-mlsirm#546 fails before tests run even though the same exact head passes the repository's Python, Rust/PyO3, package, GPU-no-skip, and fuzz jobs.

Exact reproduction from the materialized merge tree of fast-mlsirm#546:

pytest collection
  -> tests/test_cov_f_fit.py imports fast_mlsirm._core
  -> ModuleNotFoundError: No module named 'fast_mlsirm._core'

The failing central workflow is ContextualWisdomLab/.github run 30993478444, job coverage-evidence, step Measure test and docstring evidence. The target head is d111e2b1341b0daab6b813074c7a7dbcf5c24ff4. Direct target-repository CI, SAST, Security Scan, and Strix succeeded on that head, but OpenCode correctly submitted CHANGES_REQUESTED because its coverage job had no safe native-extension contract.

Security boundary

Do not solve this by:

• skipping _core-dependent tests;
• adding a pure-Python compatibility stub;
• treating any ModuleNotFoundError as success;
• enabling arbitrary network access in the untrusted execution sandbox;
• executing PR-selected build hooks or package installers;
• accepting status-only, stale-head, or unrelated workflow evidence.

The fix must preserve Rust as the production arithmetic layer and must fail closed for native ABI changes, unrelated import errors, test failures, malformed project metadata, absent peer checks, pending checks, or checks from another SHA.

Required design

Mirror the existing bounded R-package peer-deferral pattern with a dedicated PyO3/maturin gate.

1. Deterministic failure classifier

Add a production helper such as scripts/ci/python_native_extension_peer_gate.py that:

• reads a regular bounded pytest log;
• reads the exact project pyproject.toml and requires the maturin build backend;
• obtains the exact declared native module name from project metadata;
• accepts only pytest collection failures caused exclusively by the declared module being absent;
• rejects missing third-party dependencies, syntax/import errors in project code, runtime crashes, ordinary test failures, mixed errors, truncated logs, unsafe files, and ambiguous metadata;
• receives the exact base/head changed-file list and rejects deferral when Cargo.toml, Cargo.lock, Rust sources, PyO3 binding code, the build backend, module name, or packaging/ABI metadata changed.

2. Coverage workflow integration

For a configured repository pytest command:

1. capture the bounded command log;
2. record normal success when pytest succeeds;
3. on failure, invoke the classifier;
4. when and only when the failure is safely classifiable, mark the local sandbox result as deferred to native peer evidence, not as standalone proof;
5. publish an explicit machine-readable flag and human-readable summary;
6. retain normal fail-closed behavior for every other result.

The central result must never state that tests passed solely because the extension was absent.

3. Exact-head peer evidence

Before approval, require all of the following successful checks on the exact PR head:

• repository Python test job;
• Rust/PyO3 test job;
• package build/install/smoke job.

Repositories may declare canonical check-name aliases in trusted base metadata, but PR text cannot choose arbitrary passing checks. Pending, skipped-required, neutral, action-required, stale, predecessor-head, status-only, self-authored, or missing evidence must block approval. GPU and fuzz checks remain independently required by repository policy when configured.

4. Change-sensitive policy

• Python/reporting-only changes may use the peer gate when native ABI inputs are unchanged.
• Any native or packaging change must be tested by a trusted current-head native build path; it cannot use the unchanged-extension deferral.
• A later base update or new head invalidates all prior classification and peer evidence.

TDD sequence

1. Add failing classifier tests first.
2. Cover exact fast_mlsirm-shaped maturin metadata and _core collection failure.
3. Add adversarial tests for mixed import errors, undeclared modules, changed Rust/ABI inputs, truncated logs, symlinks, oversized logs, pending/stale/wrong-head checks, and misleading check names.
4. Implement the classifier.
5. Add a workflow contract that proves the configured pytest path uses the bounded classifier and emits the peer-required marker.
6. Add a deterministic peer-check gate test.
7. Re-run the current fast-mlsirm#546 exact-head review and require a new independent verdict.

Quality gates

• production statement coverage 100%;
• production branch coverage 100%;
• public module/class/function docstrings 100%;
• Python 3.10 and current stable Python compatibility;
• bounded regular-file reads;
• no credential or runner-command-file exposure to PR code;
• permanent tests in the central quality workflow;
• CHANGELOG.md and APA 7 doctoring;
• no one-shot write-capable repair workflow in the final tree.

Documentation and standards

Doctoring should cite, in APA 7th format, the authoritative GitHub Actions check-run/current-head semantics, Python import-system behavior, PyO3 and maturin packaging documentation, and the repository's existing sandbox/SSDF threat boundary. Documentation must distinguish local sandbox deferral from successful native testing and must make no formal conformance claim.

Acceptance criterion

fast-mlsirm#546 at exact head d111e2b1341b0daab6b813074c7a7dbcf5c24ff4 can receive a central OpenCode decision only after the bounded classifier identifies the unchanged native-extension limitation and the exact-head Python, Rust/PyO3, and package jobs are independently verified successful. No test is skipped and no branch-protection requirement is bypassed.