Refactor: unify the three divergent Rust-availability probes behind one resolver

[lodyai]

Summary

Three layers probe the same "is the Rust extension available?" question, and
they can disagree:

• cuprum/_rust_backend.py:8-30 — is_available(), uncached
  (importlib.import_module on every call).
• cuprum/rust.py:8-23 — is_rust_available(), a thin pass-through.
• cuprum/_backend.py:71-89 — _check_rust_available(), lru_cached and
  honouring the _RUST_AVAILABILITY_FOR_TESTING override.

Problem

The cached, override-aware _check_rust_available() is what actually governs
dispatch, but the public is_rust_available() bypasses both the cache and the
test override. A caller using the documented public API can therefore observe a
different availability than the dispatcher uses — a real inconsistency in how the
optional extension's absence is handled.

Proposed resolution

• Route the public is_rust_available() (and the consumers of
  _rust_backend.is_available()) through the same cached / override-aware
  resolver used by dispatch, so there is one source of truth.
• If an uncached probe is deliberately retained, document explicitly in
  rust.py that it does not honour the backend cache or the test override.

Verification

• Unit test asserting the public probe and the dispatch probe agree, including
  under the test override.
• make check-fmt lint test green.

References

• Cuprum refactoring audit — consistency / three divergent availability probes.

[coderabbitai]

🔗 Related PRs

leynos/ortho-config#327 - Accept Cargo orthohelp dispatch (#326) [merged]
#59 - Update maturin pin to latest stable (#27) [merged]
leynos/agent-template-python#12 - Align Python template docs and scripting guidance with cuprum standards [merged]
#98 - Refresh repository documentation standards [merged]
#110 - Stabilise invalid pymodule compile-fail baseline [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Route is_rust_available() through _check_rust_available() so a single cached, override-aware resolver governs both public API and internal dispatch.
• Retain _rust_backend.is_available() as the raw, uncached probe for skip-guards that must detect physical extension presence.
• Document the caching and override behaviour in the public function's docstring.
• Add a parametrised test asserting probe agreement under normal and override conditions.

Design Choices

Design Choice 1: Should skip-guard fixtures continue using the raw `_rust_backend.is_available()` probe?

Options Considered:

1. Leave skip-guards calling _rust_backend.is_available() directly; only change the public is_rust_available().
2. Route all callers through _check_rust_available() and reset overrides before skip-guards run.

Chosen Option: 1

Rationale: Skip-guards require the true physical state; option 2 introduces fragile ordering dependencies and gains nothing.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Unify the Public Probe with the Dispatch Resolver

Route is_rust_available() through the same cached, override-aware _check_rust_available() function that governs backend dispatch. This ensures a single source of truth for availability state.

Task 1: Delegate `is_rust_available()` to the Cached Resolver

Change the public probe to call the dispatcher's resolver instead of the raw backend probe.

• Update the import statement in cuprum/rust.py to import _check_rust_available from cuprum._backend instead of (or in addition to) importing _rust_backend.
• Modify is_rust_available() to return _check_rust_available() rather than _rust_backend.is_available().
• Retain the _rust_backend import only if other code in rust.py requires it; otherwise remove it to keep the module minimal.

Task 2: Document Caching and Override Behaviour

Add explicit documentation to the public probe's docstring so callers understand that results are cached and may reflect a test override.

Expand the docstring of is_rust_available() in cuprum/rust.py to state:

• The result is cached for the process lifetime after the first call.
• The function honours the _RUST_AVAILABILITY_FOR_TESTING internal override used by test fixtures.
• Consumers needing an uncached, override-unaware probe must use cuprum._rust_backend.is_available() directly (internal API, not guaranteed stable).

🤖 Prompt for AI agents

Implement Phase 1: unify the public `is_rust_available()` API with the cached,
override-aware `_check_rust_available()` resolver so that a single source of
truth governs both public and internal availability state.

**File to modify:** `cuprum/rust.py`

- Update the import statement to import `_check_rust_available` from
`cuprum._backend` instead of (or in addition to) importing `_rust_backend`
- Modify the body of `is_rust_available()` to return `_check_rust_available()`
rather than `_rust_backend.is_available()`
- Remove the `_rust_backend` import if no other code in `rust.py` requires it;
retain it only if necessary
- Expand the docstring of `is_rust_available()` to clearly state:
  - The result is cached for the process lifetime after the first call
- The function honours the `_RUST_AVAILABILITY_FOR_TESTING` internal override
used by test fixtures
- Consumers needing an uncached, override-unaware probe must use
`cuprum._rust_backend.is_available()` directly (internal API, not guaranteed
stable)

Phase 2: Add Consistency Tests

Introduce a unit test that asserts the public probe and the dispatch probe always agree, including under the test override.

Task 1: Create Probe-Agreement Test

Add a test verifying that is_rust_available() and _check_rust_available() return identical values.

• Create a new test function (or extend an existing test module such as cuprum/unittests/test_rust_extension.py or cuprum/unittests/test_backend.py) that:
  • Calls both cuprum.is_rust_available() and cuprum._backend._check_rust_available().
  • Asserts they return the same boolean value.
• Ensure the test runs after the autouse _clear_backend_cache fixture so caches are in a known state.

Task 2: Test Agreement Under Override Conditions

Verify consistency when the test override is active.

• Parametrise or duplicate the agreement test to cover three override states via set_rust_availability_for_testing:
  • is_available=True (forced available)
  • is_available=False (forced unavailable)
  • is_available=None (normal probing)
• Assert that is_rust_available() and _check_rust_available() still agree in each case.

Task 3: Verify Existing Tests Remain Valid

Confirm that tests monkeypatching _rust_backend.is_available still exercise the public probe correctly.

• Review cuprum/unittests/test_rust_extension.py tests test_public_probe_reports_unavailable_when_backend_unavailable and test_public_probe_reports_available_when_backend_available.
• Confirm these tests still pass after the change because:
  • The autouse _clear_backend_cache fixture clears the lru_cache before each test.
  • _check_rust_available() delegates to the (now-patched) _rust_backend.is_available() when the override is None.
• If any tests fail, update them to use set_rust_availability_for_testing instead of monkeypatching, aligning with the canonical override mechanism.

🤖 Prompt for AI agents

Implement Phase 2: add consistency tests asserting that the public probe
`is_rust_available()` and the dispatch resolver `_check_rust_available()` always
agree, including under override conditions.

**Files to create or modify:** `cuprum/unittests/test_rust_extension.py` or
`cuprum/unittests/test_backend.py` (extend an existing module or create a new
test function as appropriate)

- Add a test function that calls both `cuprum.is_rust_available()` and
`cuprum._backend._check_rust_available()` and asserts they return the same
boolean value
- Ensure this test runs after the autouse `_clear_backend_cache` fixture so
caches are in a known state
- Parametrise (or duplicate) the agreement test to cover three override states
using `set_rust_availability_for_testing`:
  - `is_available=True` (forced available)
  - `is_available=False` (forced unavailable)
  - `is_available=None` (normal probing)
- Assert that `is_rust_available()` and `_check_rust_available()` agree under
each of those three states
- Review `test_public_probe_reports_unavailable_when_backend_unavailable` and
`test_public_probe_reports_available_when_backend_available` in
`cuprum/unittests/test_rust_extension.py`; if either test fails after the Phase
1 change, update it to use `set_rust_availability_for_testing` rather than
monkeypatching `_rust_backend.is_available`

Research

The codebase has a three-layer availability architecture: _rust_backend.is_available() performs the raw importlib probe, rust.is_rust_available() wraps it as the public API, and _backend._check_rust_available() caches the result via lru_cache whilst honouring the _RUST_AVAILABILITY_FOR_TESTING testing override. The dispatcher uses _check_rust_available(), but the public API bypasses both cache and override. Import analysis confirms that routing rust.py through _backend.py introduces no circular dependency. Skip-guard fixtures in conftest.py and BDD test files intentionally use the raw probe to reflect physical extension presence rather than test-override state.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: unify the public `is_rust_available()` API with the cached,
override-aware `_check_rust_available()` resolver so that a single source of
truth governs both public and internal availability state.

**File to modify:** `cuprum/rust.py`

- Update the import statement to import `_check_rust_available` from
`cuprum._backend` instead of (or in addition to) importing `_rust_backend`
- Modify the body of `is_rust_available()` to return `_check_rust_available()`
rather than `_rust_backend.is_available()`
- Remove the `_rust_backend` import if no other code in `rust.py` requires it;
retain it only if necessary
- Expand the docstring of `is_rust_available()` to clearly state:
  - The result is cached for the process lifetime after the first call
- The function honours the `_RUST_AVAILABILITY_FOR_TESTING` internal override
used by test fixtures
- Consumers needing an uncached, override-unaware probe must use
`cuprum._rust_backend.is_available()` directly (internal API, not guaranteed
stable)
===============================================================================

Task: 2

Implement Phase 2: add consistency tests asserting that the public probe
`is_rust_available()` and the dispatch resolver `_check_rust_available()` always
agree, including under override conditions.

**Files to create or modify:** `cuprum/unittests/test_rust_extension.py` or
`cuprum/unittests/test_backend.py` (extend an existing module or create a new
test function as appropriate)

- Add a test function that calls both `cuprum.is_rust_available()` and
`cuprum._backend._check_rust_available()` and asserts they return the same
boolean value
- Ensure this test runs after the autouse `_clear_backend_cache` fixture so
caches are in a known state
- Parametrise (or duplicate) the agreement test to cover three override states
using `set_rust_availability_for_testing`:
  - `is_available=True` (forced available)
  - `is_available=False` (forced unavailable)
  - `is_available=None` (normal probing)
- Assert that `is_rust_available()` and `_check_rust_available()` agree under
each of those three states
- Review `test_public_probe_reports_unavailable_when_backend_unavailable` and
`test_public_probe_reports_available_when_backend_available` in
`cuprum/unittests/test_rust_extension.py`; if either test fails after the Phase
1 change, update it to use `set_rust_availability_for_testing` rather than
monkeypatching `_rust_backend.is_available`

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!