Align design-doc §13.2 with the backend probe/resolve seam

[leynos]

Summary

Follow-up to the merged #224 backend seam refactor. CodeRabbit's post-merge "Developer Documentation" warning flagged that docs/cuprum-design.md still described get_stream_backend() as delegating to _check_rust_available(), conflicting with the implemented probe→resolve seam.

The stale wording is in §13.2 (the "Extension Architecture" overview): it said the cached _check_rust_available() resolver wraps the probe "for is_rust_available() and get_stream_backend()", implying a direct delegation. §13.3 and §13.4 already describe the authoritative seam model (_parse_backend_value → _probe_rust_availability → _resolve_backend, with only _probe_rust_availability() wrapping the cached _check_rust_available()).

Change

Qualify the §13.2 sentence so get_stream_backend() is fed through the _probe_rust_availability() seam, mirroring §13.3, and add a one-line cross-reference to §13.4's full resolution plus an explicit "does not delegate to _check_rust_available() directly". The document now keeps one authoritative backend model; the high-level flowchart (which never claimed direct delegation) is unchanged.

Docs-only.

Validation

make markdownlint (49 files, 0 errors; spelling sub-target clean) and make nixie (all Mermaid diagrams validated) pass.

Summary by Sourcery

Documentation:

• Update §13.2 of the Cuprum design document to describe that get_stream_backend() uses the _probe_rust_availability() seam and clarify it does not delegate directly to _check_rust_available(), adding a cross-reference to §13.4’s full resolution flow.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Documentation-only update aligning the design doc’s description of the backend probe/resolve seam with the actual implementation, clarifying how get_stream_backend() uses the _probe_rust_availability() seam rather than delegating directly to _check_rust_available().

Sequence diagram for the updated backend probe/resolve seam used by get_stream_backend

sequenceDiagram
    participant Client
    participant get_stream_backend
    participant _parse_backend_value
    participant _probe_rust_availability
    participant _check_rust_available
    participant _resolve_backend

    Client->>get_stream_backend: get_stream_backend()
    get_stream_backend->>_parse_backend_value: _parse_backend_value(config_backend)
    _parse_backend_value-->>get_stream_backend: backend_value

    get_stream_backend->>_probe_rust_availability: _probe_rust_availability(backend_value)
    _probe_rust_availability->>_check_rust_available: _check_rust_available()
    _check_rust_available-->>_probe_rust_availability: rust_available
    _probe_rust_availability-->>get_stream_backend: probed_backend

    get_stream_backend->>_resolve_backend: _resolve_backend(probed_backend)
    _resolve_backend-->>get_stream_backend: backend_impl
    get_stream_backend-->>Client: backend_impl

Loading

File-Level Changes

Change	Details	Files
Align §13.2 backend extension-architecture description with the implemented probe→resolve seam.	Clarify that get_stream_backend() is routed through the _probe_rust_availability() seam instead of directly delegating to _check_rust_available(). Add cross-reference to §13.4’s authoritative _parse_backend_value → _probe_rust_availability → _resolve_backend flow. Explicitly state that get_stream_backend() does not call _check_rust_available() directly, removing ambiguity with other sections.	docs/cuprum-design.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d0173f10-b48b-4e3b-824d-57702a53b838

📥 Commits

Reviewing files that changed from the base of the PR and between 302858c and bc8e0a5.

📒 Files selected for processing (1)

• docs/cuprum-design.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• leynos/shared-actions (auto-detected)
• leynos/pylint-pypy-shim (auto-detected)
• leynos/whitaker (auto-detected)

---

Summary

• Updated docs/cuprum-design.md §13.2 to accurately describe stream backend selection via get_stream_backend() using the _probe_rust_availability() seam.
• Added a cross-reference to §13.4 for the full backend resolution flow (_parse_backend_value → _probe_rust_availability → _resolve_backend) and clarified that get_stream_backend() does not delegate directly to _check_rust_available().
• Validated with make markdownlint and make nixie.

Walkthrough

Update the Rust-extension stream dispatch documentation to describe the _probe_rust_availability() seam, distinguish it from _check_rust_available(), and reference the complete backend-resolution flow in Section 13.4.

Changes

Rust dispatch documentation

Layer / File(s)	Summary
Clarify backend resolution seam docs/cuprum-design.md	Document the _parse_backend_value → _probe_rust_availability → _resolve_backend flow, clarify that get_stream_backend() does not directly call _check_rust_available(), and link to Section 13.4.

Possibly related PRs

• leynos/cuprum#136: Relates to get_stream_backend() dispatch handling and backend exhaustiveness.
• leynos/cuprum#143: Relates to the unified Rust-availability probe and backend resolution contract.
• leynos/cuprum#224: Relates to the documented stream-backend resolution seam.

Poem

Name the probe and trace the flow,
Let backend resolution show.
No direct call hides between,
Section thirteen keeps it clean.

🚥 Pre-merge checks | ✅ 19 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Testing (Property / Proof)	❓ Inconclusive	Placeholder; will replace after code inspection.	Do not rely on summary alone; verify the diff and surrounding document sections.

✅ Passed checks (19 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the docs update to align §13.2 with the backend probe/resolve seam.
Description check	✅ Passed	The description matches the documentation-only backend seam clarification in the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Testing (Overall)	✅ Passed	Docs-only change in docs/cuprum-design.md; no code or test files changed, so no new behaviour required test coverage.
User-Facing Documentation	✅ Passed	Pass: treat this as non-applicable; keep the seam clarification in design docs, since no user-facing behaviour changed and the users' guide already covers backend choice.
Developer Documentation	✅ Passed	Approve: §13.2/§13.4 now record the backend seam, and docs/developers-guide.md already matches; no roadmap or execplan update is needed.
Module-Level Documentation	✅ Passed	Accept it: this PR only amends docs/cuprum-design.md, so the module-level docstring rule is not engaged by the changed files.
Testing (Unit And Behavioural)	✅ Passed	Docs-only change in docs/cuprum-design.md; no code, API, or workflow changed, so unit and behavioural tests are not applicable.
Testing (Compile-Time / Ui)	✅ Passed	Docs-only edit; no compile-time or UI behaviour changed, so trybuild or snapshot coverage is not applicable.
Unit Architecture	✅ Passed	Docs-only change; no runtime code, dependencies, queries, or side-effects were introduced, and the backend seam description now matches the existing architecture.
Domain Architecture	✅ Passed	PASS: The PR only clarifies documentation about backend seams; it adds no domain, adapter, or persistence code and changes no boundary behaviour.
Observability	✅ Passed	PASS: The PR only edits docs/cuprum-design.md; no runtime behaviour, logging, metrics, tracing, or alerts changed, so observability additions are not required.
Security And Privacy	✅ Passed	Docs-only wording change; it adds no secrets, credentials, permissions, or data exposure, and merely clarifies an existing backend seam.
Performance And Resource Use	✅ Passed	PASS — Only docs/cuprum-design.md changed; no executable code, loops, allocations, I/O, or blocking paths were added.
Concurrency And State	✅ Passed	Docs-only wording change; no shared mutable state, async execution, locks, ordering, or task lifetimes were introduced.
Architectural Complexity And Maintainability	✅ Passed	Docs-only wording change; it clarifies an existing seam and adds no new abstraction, layer, registry, or dependency edge.
Rust Compiler Lint Integrity	✅ Passed	Only docs/cuprum-design.md changed; no Rust sources, lint suppressions, artificial anchors, or new clones were introduced.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs-backend-seam-alignment

---

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

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[codescene-access]

No quality gates enabled for this code.

[buzzybee-df12]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[pandalump]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.