fix(openfold3): load the selected product runtime

[chaofengw-nv]

Background

OpenFold3's qualification executable is built in a separate native build tree, but its E2E test selects backend and model plugins from the installed wheel. The executable's default library search path can load the source-built runtime against those wheel plugins. Strict product-build identity checks then reject the backend before structure prediction begins.

Exit Criteria

• Load the runtime and core paired with the selected wheel plugins.
• Support copied and symlinked staged runtime roots.
• Preserve prediction acceptance criteria and the parent process environment.
• Verify the real qualification executable across two distinct sets of runtime libraries.

Implementation

Resolve the staged core library and prepend its companion loader directory to LD_LIBRARY_PATH for the qualification subprocess. Require that companion loader to exist. This keeps the runtime selection local to OpenFold3's E2E invocation.

The regression compiles the existing qualification executable and two sets of small CPU runtime/core/backend fixtures with different build identities. It tests both staging layouts with an inherited library path that points to the wrong build, plus missing-loader rejection.

Change categories

• CI or developer tooling

Validation

Commands and Results

• python -m pytest families/openfold3/tests/test_e2e_runtime.py -q: the two cross-build layout cases failed before the fix with a runtime/core/backend build mismatch and passed after the fix.
• python -m pytest families/openfold3/tests -q -k 'not official_checkpoint_e2e': 20 passed, 1 official-checkpoint E2E case deselected; includes the added missing-loader case.
• python -m ruff check families/openfold3/tests/test_e2e.py families/openfold3/tests/test_e2e_runtime.py: passed.
• python -m ruff format --check families/openfold3/tests/test_e2e.py families/openfold3/tests/test_e2e_runtime.py: passed.
• clang-format --dry-run --Werror families/openfold3/tests/cpp/fake_build_identity.cpp families/openfold3/tests/cpp/fake_qualification_runtime.cpp: passed.
• python -m tools.community_ci impact --base github/main: only openfold3 selected.
• python -m tools.community_ci source-quality --base github/main: passed; 128 architecture and source-quality tests passed.
• git diff --check github/main...HEAD: passed.

Hardware, Environment, and Revisions

CPU execution on Linux x86_64 with Python 3.12.3 and the system C++ compiler. The regression uses synthetic runtime fixtures, the production qualification executable, and the real OS dynamic linker; it needs no CUDA device or checkpoint. Tested change: 3de2a56e5ec820e785a66835433dd897d99aff2b, based on 5c0bedd8549fd60eec3340a51477d83a20d91c54.

Not Run / Remaining Gaps

Full official-checkpoint GPU E2E has not been rerun. The CPU evidence verifies product-library selection and does not establish structure-prediction accuracy or performance. Protected premerge validation remains required.

Contributor Self-Review

• I have completed a self-review of this change.

Notes For Future Readers

The qualification executable remains separately compiled against the same source interfaces. Its child environment must select the wheel's loader and core together with the wheel's plugins. This also supports the product-build identity enforcement introduced in #1190. Prediction thresholds, runtime loader guards, shared CI code, and public interfaces are unchanged.

Risk level

• Low

The change affects one family's test subprocess environment and is covered by actual compilation and dynamic loading. Official-checkpoint GPU validation is still needed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8ef210a1-734a-4d71-a72c-62f0779b5e1c

📥 Commits

Reviewing files that changed from the base of the PR and between 5c0bedd and 3de2a56.

📒 Files selected for processing (4)

• families/openfold3/tests/cpp/fake_build_identity.cpp
• families/openfold3/tests/cpp/fake_qualification_runtime.cpp
• families/openfold3/tests/test_e2e.py
• families/openfold3/tests/test_e2e_runtime.py

Included review availability: Your plan provides up to 12 included reviews per hour; 10 remain after this review.

---

📝 Summary

Summary

OpenFold3 qualification E2E execution now selects the runtime and core libraries paired with the selected wheel plugins.

_run_native resolves the staged core library, requires its companion loader, and prepends the loader directory to LD_LIBRARY_PATH for the qualification subprocess. The parent environment remains unchanged.

New CPU regression fixtures validate copied and symlinked runtime roots, distinct build identities, incorrect inherited library paths, and missing-loader rejection. Prediction acceptance criteria remain unchanged.

Validation passed for OpenFold3 runtime tests, selected OpenFold3 tests, Ruff, formatting, C++ formatting, impact analysis, and whitespace checks. Official-checkpoint GPU E2E validation remains outstanding.

Architecture impact

• Family-owned files: All changes remain under families/openfold3/tests/.
• Changed shared surfaces: The qualification subprocess receives a selected loader directory through LD_LIBRARY_PATH. No shared implementation or cross-family surface changed.
• New dependency directions: The qualification executable now depends on the staged core library and its companion runtime loader.
• Affected consumers: OpenFold3 native qualification tests and their test fixtures.
• Unresolved blast-radius questions: Production GPU behavior with official checkpoints and runtime combinations remains unverified.

HUMAN REVIEW REQUIRED — official-checkpoint GPU E2E validation is outstanding.

Walkthrough

OpenFold3 test support now validates build identities across fake runtime components. Native qualification execution selects the staged runtime directory, verifies its companion loader, and preserves inherited loader paths. End-to-end tests cover copied, symlinked, and incomplete runtime layouts.

Changes

OpenFold3 runtime loading

Layer / File(s)	Summary
Runtime identity and qualification task families/openfold3/tests/cpp/fake_build_identity.cpp, families/openfold3/tests/cpp/fake_qualification_runtime.cpp	The fake runtime exports the test build ID, validates backend and runtime build IDs, and returns a test prediction when validation succeeds.
Selected runtime execution families/openfold3/tests/test_e2e.py	_run_native resolves the core library directory, requires the companion runtime loader, and prepends that directory to LD_LIBRARY_PATH.
Runtime layout end-to-end coverage families/openfold3/tests/test_e2e_runtime.py	Tests build separate native and wheel-style products and cover copied, symlinked, preserved-environment, and missing-loader cases.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Test
  participant _run_native
  participant SelectedRuntime
  participant QualificationExecutable
  Test->>_run_native: invoke qualification executable
  _run_native->>SelectedRuntime: resolve core and companion loader
  _run_native->>QualificationExecutable: launch with selected LD_LIBRARY_PATH
  QualificationExecutable-->>Test: return validated build identity

Loading

Merge Risk: ⚪ Minimal · up to 3de2a

Qualification execution now loads the runtime paired with the selected wheel libraries while preserving the parent environment. The changed runtime-selection behavior is covered by targeted regression tests, with no concrete current-head merge risk identified.

🚥 Pre-merge checks | ✅ 8 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (8 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Family Ownership Boundary	✅ Passed	PASS. The pull request changes only families/openfold3. The new C++ fixtures use the OpenFold3 contract in families/openfold3/include/trtmc/openfold3/structure_prediction.h and the shared loader c…
Shared Semantic Neutrality	✅ Passed	PASS: The pull request changes only families/openfold3/tests/cpp/* and families/openfold3/tests/test_e2e*.py. These are C++ test and E2E directories excluded by the check. The changed behavior is …
Benchmark Validation Integrity	✅ Passed	PASS. The change does not alter benchmark or performance accounting. In families/openfold3/tests/test_e2e.py, _run_native only adds a child-process LD_LIBRARY_PATH and companion-loader check; it…
Shared Change Blast Radius	✅ Passed	The pull request changes only families/openfold3/**: one OpenFold3 E2E helper, two OpenFold3 test fixtures, and one OpenFold3 runtime test module. It does not change core runtime code, shared CI cod…
Title check	✅ Passed	The title clearly identifies the OpenFold3 runtime-selection fix and matches the main change.
Description check	✅ Passed	The description covers the required background, exit criteria, implementation, change category, validation evidence, environment, remaining gaps, self-review, future notes, and risk rationale.

---

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