Apply assorted consistency and dead-code cleanups (#129)

[lodyai]

Summary

This branch applies the cluster of small consistency and dead-code fixes from the refactoring audit, gated together as one atomic change.

Closes #129.

Each item is individually trivial; they are grouped because none warrants its own PR:

• get_stream_backend exhaustiveness — a terminal case _: raise AssertionError(...) stops a future StreamBackend member silently falling off the match and returning None typed as StreamBackend.
• ExecHook provenance — imported from its definition site cuprum.events, dropped from cuprum.context's public re-export, and demoted to a TYPE_CHECKING import in context (annotations-only use).
• Spurious type: ignore — removed from logging_hooks.py; the fields are already HookRegistration | None.
• Dead FD aliases — _extract_reader_fd / _extract_writer_fd inlined to _extract_stream_fd and deleted.
• Lazy imports / import cycle — _run_before_hooks relocated into the leaf module cuprum._pipeline_types, turning the in-function imports of _StageObservation / _EventDetails / _run_before_hooks into top-level imports; the _pipeline_spawn.py re-export shim is deleted.
• en-GB spelling — "Programme" → "Program" and "serialises" → Oxford "serializes".

Review walkthrough

• Start with cuprum/_backend.py for the exhaustiveness guard, and cuprum/unittests/test_backend.py for its test.
• Then cuprum/init.py and cuprum/context.py for the ExecHook provenance fix.
• cuprum/_pipeline_types.py gains _run_before_hooks; cuprum/_process_lifecycle.py, cuprum/_pipeline_stage_streams.py, and cuprum/_pipeline_internals.py switch to top-level imports; cuprum/_pipeline_spawn.py is removed.
• cuprum/_pipeline_streams.py and cuprum/unittests/test_pipeline_stream_backend_selection.py for the FD-alias inlining.
• Finish with cuprum/logging_hooks.py and cuprum/adapters/logging_adapter.py for the type: ignore removal and spelling fixes.

Validation

• make check-fmt: pass
• make lint: pass
• make typecheck: pass
• make test: pass (Python: 654 passed, 39 skipped; Rust: 29 passed)
• make markdownlint: pass
• coderabbit review --agent: 0 findings

Notes

The wheel-build snapshot (test_maturin_build.ambr) drops cuprum/_pipeline_spawn.py from the recorded package file list.

Summary by Sourcery

Tighten backend and pipeline behaviour while cleaning up dead code, imports, and spelling across the package.

Bug Fixes:

• Guard stream backend selection with an assertion for unhandled StreamBackend members and add a regression test.
• Ensure Rust pump FD extraction uses a single stream FD helper and update tests accordingly.

Enhancements:

• Centralize pipeline execution hook collection in _pipeline_types to enable top-level imports and simplify pipeline internals.
• Replace lazy and TYPE_CHECKING-only imports with direct top-level imports to avoid import cycles and clarify module responsibilities.
• Remove unused helper functions and the obsolete _pipeline_spawn shim to reduce dead code and simplify the pipeline code paths.
• Adjust ExecHook export provenance so it is defined in cuprum.events and imported where needed without re-exporting from context.
• Normalize terminology and spelling in user-facing strings and docs (program/programme, serializes/serialises).
• Simplify logging hook registration teardown by removing unnecessary type-ignore annotations.

Documentation:

• Consolidate the performance extension foundation ExecPlan into one canonical artefact checklist.

Tests:

• Update pipeline stream backend selection tests to use the unified FD extraction helper and add coverage for the backend exhaustiveness assertion.

Chores:

• Update the maturin build snapshot to reflect removal of the _pipeline_spawn module from the package file list.

References

• Lody session

[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: 2d3ab638-a7ac-4d16-a55e-b6377e3fa0c4

📥 Commits

Reviewing files that changed from the base of the PR and between 980bdcf and 5511ece.

📒 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

• Hardened get_stream_backend() with a final unhandled-backend exhaustiveness branch and added regression coverage.
• Corrected ExecHook import provenance by moving the public source to cuprum.events, removing its cuprum.context re-export, and updating public-API tests and changelog migration notes.
• Removed unnecessary type: ignore usage and other minor consistency cleanups (including normalised en-GB spelling/terminology).
• Simplified pipeline internals: inlined/deleted redundant FD helper aliases, consolidated shared pipeline type imports around _pipeline_types, relocated pipeline hook logic into the dependency-safe boundary, and deleted _pipeline_spawn.py (updating the wheel snapshot accordingly).
• Updated documentation by consolidating duplicated artefact sections and expanding guidance on pipeline helper ownership/boundaries and ExecHook migration (users/developers/design docs).

Covers the cleanup objectives tracked in issue #129, with reported validation passing formatting, linting, type checking, tests, Markdown linting, and the Rust suite.

Walkthrough

This PR relocates ExecHook ownership, adds exhaustive backend handling, consolidates pipeline imports around shared types, removes redundant stream FD helpers, and updates tests, snapshots, documentation, and wording.

Changes

Consistency and pipeline cleanup

Layer / File(s)	Summary
Public ExecHook contract cuprum/__init__.py, cuprum/context/__init__.py, cuprum/unittests/test_public_api.py, CHANGELOG.md, docs/...	Re-export ExecHook from cuprum and cuprum.events, remove it from cuprum.context, and document and test the new import path.
Backend and logging consistency cuprum/_backend.py, cuprum/unittests/test_backend.py, cuprum/logging_hooks.py, cuprum/adapters/logging_adapter.py	Raise an assertion for unhandled backend members, remove redundant assignment suppressions, and update spelling and terminology.
Pipeline module consolidation cuprum/_pipeline_types.py, cuprum/_pipeline_internals.py, cuprum/_process_lifecycle.py, cuprum/_pipeline_stage_streams.py, cuprum/_subprocess_execution.py, cuprum/unittests/..., docs/...	Use shared pipeline types for top-level imports, redirect process spawning to _process_lifecycle, remove the spawn shim, and update related tests, snapshots, and documentation.
Unified stream FD extraction cuprum/_pipeline_streams.py, cuprum/unittests/test_pipeline_stream_backend_selection.py	Replace reader and writer FD wrappers with _extract_stream_fd() and validate Rust dispatch, Python fallback, and blocking-mode rollback.

Possibly related issues

• leynos/cuprum#130 — Covers the same backend exhaustiveness and pipeline/module cleanup objectives.

Possibly related PRs

• leynos/cuprum#157 — Directly concerns the ExecHook export split between cuprum.context and the top-level package.

Suggested labels: Issue

Suggested reviewers: leynos

Poem

Move hooks to their proper home,
Let stream aliases cease to roam,
Untangle pipelines thread by thread,
Make unknown backends raise dread,
And keep each test in steady tone.

🚥 Pre-merge checks | ✅ 20

✅ Passed checks (20 passed)

Check name	Status	Explanation
Title check	✅ Passed	PASS: The title matches the #129 cleanup scope and includes the required issue reference.
Description check	✅ Passed	PASS: The description clearly describes the same cleanup and refactoring changes in the diff.
Linked Issues check	✅ Passed	PASS: The changes implement the #129 cleanup tasks, including backend exhaustiveness, ExecHook provenance, dead aliases, pipeline import cleanup, and spelling fixes.
Out of Scope Changes check	✅ Passed	PASS: The diff stays within the cleanup scope; the added tests, docs, and snapshot updates directly support the listed fixes.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Testing (Overall)	✅ Passed	Tests cover the changed behaviour: backend exhaustiveness, ExecHook provenance, and Rust/Python dispatch with FD blocking and fallback; cache-reset fixtures prevent cross-test vacuity.
User-Facing Documentation	✅ Passed	PASS: docs/users-guide.md clearly documents the ExecHook import-path change and marks the old cuprum.context path unsupported; the migration note is also mirrored in CHANGELOG.md.
Developer Documentation	✅ Passed	PASS: docs/developers-guide.md and docs/cuprum-design.md document ExecHook provenance and pipeline ownership; roadmap/execplan entries remain current.
Module-Level Documentation	✅ Passed	PASS: every Python module inspected has a module docstring; the changed pipeline and adapter modules describe purpose and cross-module relationships, and none is undocumented.
Testing (Unit And Behavioural)	✅ Passed	PASS: Added unit tests cover backend assertion/error paths and public API invariants; observe and pipeline runtime suites exercise real command execution boundaries.
Testing (Property / Proof)	✅ Passed	No new range-wide invariant or proof obligation appears; unit tests already cover backend transitions and detach idempotence.
Testing (Compile-Time / Ui)	✅ Passed	Wheel-build output is guarded by a focused normalised snapshot; no new Rust/TS compile-time behaviour is added here.
Unit Architecture	✅ Passed	PASS: the fallible env-backed backend query stays explicit, ExecHook provenance is clarified, and pipeline helpers were split without adding hidden side-effects.
Domain Architecture	✅ Passed	PASS: Domain-facing types stay in core/events, adapter code stays in adapters, and the PR only refactors private pipeline/exports without leaking infrastructure concerns.
Observability	✅ Passed	Keep PASS: runtime paths already emit structured start/exit/observe events and logs, and the new backend guard is a defensive AssertionError with a clear message.
Security And Privacy	✅ Passed	Changes are limited to import/export cleanup, an exhaustiveness guard, logging doc tweaks, and test updates; no secrets, auth bypasses, unsafe inputs, or broad permissions added.
Performance And Resource Use	✅ Passed	No new unbounded loops, repeated I/O, blocking work, or extra collection growth were introduced; the changes are refactors and constant-time guards.
Concurrency And State	✅ Passed	PASS: Pipeline task ownership is explicit, and tests cover concurrent emits, cancellation, timeout cleanup, and fail-fast teardown.
Architectural Complexity And Maintainability	✅ Passed	The shared pipeline types module centralises existing dataclasses, removes the shim, and narrows dependencies without adding a new indirection layer.
Rust Compiler Lint Integrity	✅ Passed	HEAD changes only docs/cuprum-design.md; no Rust files, lint suppressions, or clone changes were introduced, so the Rust lint rules are unaffected.

📋 Issue Planner

Built with CodeRabbit's Coding Plans for faster development and fewer bugs.

View plan used: #129

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-129-consistency-dead-code-cleanup

---

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

[sourcery-ai]

Reviewer's Guide

Tightens backend and pipeline infrastructure consistency by enforcing exhaustive stream backend selection, centralizing hook/observation types, simplifying FD extraction, and cleaning up dead code, imports, and minor docs/spelling issues while keeping behavior intact.

File-Level Changes

Change	Details	Files
Enforce exhaustiveness and test coverage for stream backend selection.	Extend get_stream_backend match with a terminal default case that raises AssertionError for unhandled StreamBackend values. Add a unit test that forces an out-of-band backend string via _read_backend_env and asserts the new AssertionError path. Import _backend in tests to support monkeypatching of _read_backend_env.	cuprum/_backend.py cuprum/unittests/test_backend.py
Inline redundant FD helper aliases into a single stream FD extractor and update tests.	Remove _extract_reader_fd and _extract_writer_fd helpers in favor of using _extract_stream_fd directly for both reader and writer. Adjust _try_rust_pump to use _extract_stream_fd for both reader and writer FDs. Update backend selection tests to monkeypatch _extract_stream_fd instead of the removed helpers and create explicit reader/writer sentinels.	cuprum/_pipeline_streams.py cuprum/unittests/test_pipeline_stream_backend_selection.py
Centralize pipeline hook/observation types and before-hook resolution into _pipeline_types and convert to top-level imports to avoid lazy imports and cycles.	Move _run_before_hooks implementation from _pipeline_internals into _pipeline_types alongside _ExecutionHooks and observation dataclasses, using current_context at top level. Switch _pipeline_internals, _process_lifecycle, _pipeline_stage_streams, and _subprocess_execution to import _EventDetails, _StageObservation, and _run_before_hooks from _pipeline_types instead of lazy or cross-module imports. Change _process_lifecycle to own _spawn_pipeline_processes using top-level imports of _EventDetails and _StageObservation, and delete the obsolete _pipeline_spawn shim module. Update type-checking only imports and remove now-unnecessary inline imports inside functions that previously avoided cycles.	cuprum/_pipeline_types.py cuprum/_pipeline_internals.py cuprum/_process_lifecycle.py cuprum/_pipeline_stage_streams.py cuprum/_subprocess_execution.py cuprum/_pipeline_spawn.py
Tighten ExecHook provenance and public API exposure while keeping annotations valid.	Stop re-exporting ExecHook from cuprum.context by moving its import under TYPE_CHECKING and removing it from all. Import ExecHook directly from cuprum.events in cuprum.init to keep it available at the package root while no longer routing through context.	cuprum/context.py cuprum/__init__.py
Clean up logging utilities and documentation consistency (types and spelling).	Remove unnecessary type: ignore comments when nulling out LoggingHookRegistration.start_registration and exit_registration, relying on correct Optional types. Normalize spelling to US English in package and adapter docstrings (Programme→Program, serialises→serializes). Add an artefacts section to the execplan doc describing expected Rust workspace and CI configuration outputs, aligning naming and structure.	cuprum/logging_hooks.py cuprum/adapters/logging_adapter.py cuprum/__init__.py docs/execplans/4-1-1-performance-extension-foundation.md cuprum/unittests/__snapshots__/test_maturin_build.ambr

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#129	Tighten consistency and remove small dead-code issues by: making get_stream_backend exhaustive, correcting ExecHook provenance (import from cuprum.events and stop re-exporting from cuprum.context), removing the spurious type: ignore in logging_hooks.py, and deleting the dead FD alias helpers in _pipeline_streams.py with call sites updated.	✅
#129	Eliminate lazy in-function imports and the ad-hoc sys.modules service locator in pipeline code by relocating shared pipeline dataclasses/helpers (e.g. _StageObservation, _EventDetails, _run_before_hooks and result types) into a dependency-free leaf module, switching dependent modules to top-level imports, and deleting the _pipeline_spawn.py re-export shim.	✅
#129	Standardize spelling in user-facing text to the requested conventions by changing "Programme" to "Program" in logging_adapter and aligning mixed "serialise" / "serializable" prose to en-GB-oxendict spelling.	❌	The PR changes "Programme" to "Program" as requested, but it also changes "serialises" to "serializes", which is US spelling rather than en-GB-oxendict. The issue explicitly asked to align the mixed serialise/serializable prose to en-GB-oxendict, so the spelling alignment is not fully implemented as specified.

Possibly linked issues

• Cleanup: assorted consistency & dead-code fixes (exhaustiveness, ExecHook provenance, type:ignore, lazy imports, en-GB, dead aliases) #129: PR directly completes all issue checklist items: backend exhaustiveness, ExecHook provenance, lazy import removal, FD alias cleanup, spelling.

---

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.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cuprum/unittests/test_pipeline_stream_backend_selection.py`:
- Around line 227-232: Update the test around _pump_stream_dispatch to use an
explicit writer object alongside the reader, and make the mocked
_extract_stream_fd return write_fd only for that writer and None for unknown
streams. Pass the writer to _pump_stream_dispatch so the Rust FD extraction path
is tested without incorrectly treating None as a valid writer; preserve or add a
separate assertion that writer=None uses the Python fallback.

In `@docs/execplans/4-1-1-performance-extension-foundation.md`:
- Around line 345-355: Remove one of the duplicated “Artefacts and Notes”
sections in the ExecPlan, preferably the newly added subsection around the
listed Rust, build-system, CI, and documentation artefacts. Retain a single
canonical artefact checklist with the complete expected entries.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5537f3c8-a689-46dd-829d-6adaae28b6d7

📥 Commits

Reviewing files that changed from the base of the PR and between 4037b72 and 0815998.

📒 Files selected for processing (16)

• cuprum/__init__.py
• cuprum/_backend.py
• cuprum/_pipeline_internals.py
• cuprum/_pipeline_spawn.py
• cuprum/_pipeline_stage_streams.py
• cuprum/_pipeline_streams.py
• cuprum/_pipeline_types.py
• cuprum/_process_lifecycle.py
• cuprum/_subprocess_execution.py
• cuprum/adapters/logging_adapter.py
• cuprum/context.py
• cuprum/logging_hooks.py
• cuprum/unittests/__snapshots__/test_maturin_build.ambr
• cuprum/unittests/test_backend.py
• cuprum/unittests/test_pipeline_stream_backend_selection.py
• docs/execplans/4-1-1-performance-extension-foundation.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)

💤 Files with no reviewable changes (2)

• cuprum/_pipeline_spawn.py
• cuprum/unittests/snapshots/test_maturin_build.ambr

[leynos]

@coderabbitai Have the following now been resolved?

• In docs/execplans/4-1-1-performance-extension-foundation.md the "Artefacts and Notes" section now appears twice with overlapping content; consider consolidating these into a single section to avoid confusion.
• Now that _EventDetails and _StageObservation live in _pipeline_types, there are still TYPE_CHECKING imports of these from _pipeline_internals (e.g. in _process_lifecycle and _pipeline_stage_streams); updating those to point at _pipeline_types would keep the type source-of-truth consistent.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- Documentation headings and artefact sections ---'
rg -n -i -C 12 '^## artefacts and notes|^### expected artefacts|artefacts and notes' \
  docs/execplans/4-1-1-performance-extension-foundation.md || true

printf '%s\n' '--- Relevant Python module outlines ---'
ast-grep outline \
  cuprum/_process_lifecycle.py \
  cuprum/_pipeline_stage_streams.py \
  cuprum/_pipeline_internals.py \
  cuprum/_pipeline_types.py \
  --items all --view expanded || true

printf '%s\n' '--- Pipeline type and import references ---'
rg -n -C 4 \
  'TYPE_CHECKING|_pipeline_internals|_pipeline_types|_EventDetails|_StageObservation' \
  cuprum/_process_lifecycle.py \
  cuprum/_pipeline_stage_streams.py \
  cuprum/_pipeline_internals.py \
  cuprum/_pipeline_types.py || true

Length of output: 21463

---

@leynos Mark both findings as resolved.

• docs/execplans/4-1-1-performance-extension-foundation.md now contains a single ## Artefacts and notes section, at Line 345.
• cuprum/_process_lifecycle.py and cuprum/_pipeline_stage_streams.py now import _EventDetails and _StageObservation directly from cuprum._pipeline_types. Their remaining TYPE_CHECKING imports are unrelated.

[leynos]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.

[codescene-access]

No quality gates enabled for this code.