Configure df12 Python lint gates

[lodyai]

Summary

This branch extends Cuprum's Ruff and PyPy-backed Pylint policy with every
df12-python-lints v0.1.0 message under CPython 3.14. It also adds the
release's ambrleaks scanner to make lint and repairs every finding exposed
by the new gates without adding suppressions.

The branch is stacked on PR #234,
which establishes the docstring policy this lint configuration builds upon.

Review walkthrough

• Start with the Makefile
  and project configuration
  for the pinned CPython 3.14 df12 Pylint and ambrleaks commands.
• Review the narrow ambrleaks allowlist
  for deterministic public fixture data that resembles POSIX paths.
• Review the resulting source and test repairs in
  the commit,
  including explicit assertion messages, stronger aliasing and dispatch
  structures, and urllib redirect compatibility.
• Finish with the amended
  lint architecture decision
  and developer guidance.

Validation

• make check-fmt
• make lint
• make typecheck
• make test — 815 Python tests passed, 47 skipped; all behavioural groups
  passed; all 57 Rust tests passed
• make markdownlint — 49 files, zero errors; 16 spelling-helper tests passed
• make nixie

References

• Lody session

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f633456c-3c06-4ef6-a980-2d48ce77a0b6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

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

Summary

• Configure the pinned df12-python-lints v0.1.0 policy under CPython 3.14.
• Add ambrleaks snapshot scanning to make lint with deterministic allowlisting.
• Refactor GitHub HTTP transport into benchmarks/_github_http.py with bounded retries, timeout handling, redirect validation, and cross-origin header protection.
• Enforce the boolean contract for cuprum.rust.is_rust_available().
• Improve subprocess completion handling when returncode is published before process.wait() completes.
• Remove redundant wrappers and simplify type aliases, context access, backend selection, and argument construction.
• Strengthen tests with redirect-binding coverage, Rust resolver validation, subprocess regressions, cache checks, concurrency coverage, pipeline fail-fast coverage, benchmark-ratchet validation, and clearer assertion diagnostics.
• Document the lint architecture in ADR-003 and add the debugging plan.
• Track the required property-based or bounded contract proofs in issue #275.

Validation

• Pass formatting, linting, type checking, tests, Markdown linting, and Nixie validation.

Walkthrough

The change adds lint gates, centralises benchmark GitHub transport, hardens subprocess exit handling, refactors benchmark and Cuprum helpers, and expands tests and documentation.

Changes

Quality and reliability updates

Layer / File(s)	Summary
Lint and snapshot gates Makefile, ambrleaks.toml, pyproject.toml, docs/adr-003-two-tier-python-linting.md, docs/developers-guide.md	Add pinned df12-python-lints and ambrleaks checks. Configure Pylint caching, Python versions, scanner allowlists, and lint documentation.
Shared GitHub transport benchmarks/_github_http.py, benchmarks/_validation.py, benchmarks/fetch_main_benchmark_baseline.py, cuprum/unittests/test_fetch_main_benchmark_*.py	Centralise authenticated JSON and archive requests. Add HTTPS validation, retries, timeouts, size limits, redirect handling, and transport tests.
Process-exit lifecycle cuprum/_process_lifecycle.py, cuprum/_pipeline_wait.py, cuprum/_subprocess_execution.py, cuprum/unittests/test_pipeline_wait.py, cuprum/unittests/test_subprocess_timeout.py	Use _await_process_exit for command, pipeline, and termination paths. Race process.wait() with return-code polling and add fail-fast regression coverage.
Benchmark and Cuprum maintenance benchmarks/*, cuprum/_backend.py, cuprum/catalogue.py, cuprum/sh.py, cuprum/rust.py, cuprum/context/state.py, cuprum/adapters/*	Refactor helper boundaries, validate Rust availability results, synchronise settings caching, simplify argument construction, and update subprocess annotations.
Tests and documentation cuprum/unittests/*, tests/behaviour/*, docs/debugging/*, docs/developers-guide.md	Add concurrency, benchmark ratchet, redirect, pipeline, and availability tests. Add assertion diagnostics and structured API documentation.

Sequence Diagram(s)

sequenceDiagram
  participant BenchmarkCLI
  participant GitHubHTTP
  participant GitHub
  BenchmarkCLI->>GitHubHTTP: Request baseline metadata
  GitHubHTTP->>GitHub: Send authenticated HTTPS request
  GitHub-->>GitHubHTTP: Return validated JSON
  BenchmarkCLI->>GitHubHTTP: Request archive bytes
  GitHubHTTP->>GitHub: Follow validated redirect
  GitHub-->>GitHubHTTP: Return archive
  GitHubHTTP-->>BenchmarkCLI: Return bounded archive bytes

Loading

sequenceDiagram
  participant CuprumExecution
  participant AwaitProcessExit
  participant ProcessWait
  participant ReturncodePolling
  CuprumExecution->>AwaitProcessExit: Await process completion
  AwaitProcessExit->>ProcessWait: Start process.wait()
  AwaitProcessExit->>ReturncodePolling: Poll process.returncode
  ProcessWait-->>AwaitProcessExit: Return exit code
  ReturncodePolling-->>AwaitProcessExit: Return published exit code
  AwaitProcessExit-->>CuprumExecution: Return selected exit code

Loading

Possibly related PRs

• leynos/df12-python-lints#6 — Adds the lint integration used by this change.
• leynos/cuprum#223 — Overlaps with subprocess waiting and timeout handling.
• leynos/cuprum#143 — Overlaps with Rust availability validation.

Suggested reviewers: leynos

Poem

Lint gates run in ordered rows,
Redirects guard the data flows.
Processes publish codes on time,
Tests explain each failing line.
Cuprum helpers now align.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (3 errors, 7 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Testing (Overall)	❌ Error	Tests cover URLError retries and HTTP 404 rejection, but no test exercises the implemented 429 or 5xx retry branches; an implementation that never retries HTTPError would still pass.	Add parametrised _with_retry tests for HTTP 429, 500 and another 5xx, asserting three attempts and delays, plus a non-transient boundary such as 499 or 600.
Unit Architecture	❌ Error	find_latest_artifact_download_url is a query API, but it calls _load_json_response, which performs network I/O and time.sleep retries behind a non-injectable transport.	Inject a narrow HTTP transport and sleeper at the query boundary, or keep the query pure over supplied payloads and move network retrieval into an explicit command/service.
Rust Compiler Lint Integrity	❌ Error	Reject this change: it removes #[cfg(unix)] from two private retry helpers, while every call remains in Unix-only functions, leaving both dead on Windows.	Restore #[cfg(unix)] on record_read_retry and record_write_retry, or place them in a Unix-only module; do not add an allow suppression.
User-Facing Documentation	⚠️ Warning	The users' guide documents concurrent-result validation, but it omits the new public is_rust_available() TypeError contract implemented in cuprum/rust.py and covered by tests.	Add a short 'Raises' note under Rust availability in docs/users-guide.md, including TypeError and the resolver message; add an Unreleased migration note if this is treated as breaking.
Developer Documentation	⚠️ Warning	The developer guide introduces the nonexistent tests/helpers/maturin_pins.py; the actual pin checks are in cuprum/unittests/test_maturin_pins.py.	Replace the stale path with the actual test module and document the new _await_process_exit lifecycle boundary in the developer guide or design document.
Testing (Unit And Behavioural)	⚠️ Warning	Unit coverage is broad, but the new GitHub transport and dictionary refresh lack end-to-end tests: remote tests patch build_opener, and CLI tests call main() while mocking _download_bytes.	Add a behavioural test with a local HTTPS server that runs the baseline-fetch CLI as a subprocess and exercises JSON/archive redirects, retries, authentication policy, and cache persistence.
Testing (Property / Proof)	⚠️ Warning	The PR adds redirect-binding and boolean-resolver invariants, but only finite parametrised tests; no new Hypothesis property or substantive CrossHair proof covers either contract.	Add Hypothesis properties for all redirect argument shapes/types and arbitrary resolver results, or add a substantive bounded CrossHair proof, while retaining the finite regressions.
Observability	⚠️ Warning	New _github_http.py adds HTTP retries and backoff without retry logs, metrics, or network tracing; ProgramCatalogue adds cache behaviour without cache metrics.	Add bounded-cardinality retry attempt, outcome, and latency metrics, plus safe decision logs and a network span; instrument cache initialisation and hits without URLs, tokens, or payloads.
Performance And Resource Use	⚠️ Warning	The new shared HTTP transport caps archives at 64 MiB, but _load_json_response still calls json.load(response) without a response-size bound; tests cover only archive overflow.	Add a maximum JSON response size and a bounded reader before json.load; add an oversized-JSON regression test.
Concurrency And State	⚠️ Warning	Protecting state only inside _EnvBackendSelector is insufficient: _pipeline_streams calls cached get_stream_backend() without _BACKEND_LOCK, so concurrent reads can repopulate stale backend...	Guard all backend environment/cache reads and clears with one shared lock, or enforce and document exclusive process use; add a test where an external resolver overlaps selector restoration.
Security And Privacy	❓ Inconclusive	Investigation is still in progress.	Review the changed HTTP, subprocess, context-policy, and refresh code before deciding.

✅ Passed checks (9 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change by configuring the df12 Python lint gates.
Description check	✅ Passed	The description accurately explains the lint configuration, scanner integration, code repairs, documentation changes, and validation results.
Docstring Coverage	✅ Passed	Docstring coverage is 97.40% which is sufficient. The required threshold is 80.00%.
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.
Module-Level Documentation	✅ Passed	All 222 Python modules have leading, non-empty docstrings; new modules describe their purpose, utility, and relationships to adjoining components.
Testing (Compile-Time / Ui)	✅ Passed	The PR changes no Rust or TypeScript files; the existing Rust trybuild UI harness covers compile-time checks. Structured outputs use focused assertions and redacted Syrupy snapshots.
Domain Architecture	✅ Passed	Keep the check passing: core policy helpers are dependency-light, telemetry uses protocols, and GitHub, cache, subprocess, and benchmark transport concerns remain behind dedicated modules.
Architectural Complexity And Maintainability	✅ Passed	New modules isolate real HTTP, ratio, stream, policy, tracing and backend seams; direct consumers, tests, reuse rules and invariants are documented, with no production import cycles found.

✨ Finishing Touches 💡 2

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch configure-df12-lints

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch configure-df12-lints

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[sourcery-ai]

Reviewer's Guide

Configures a new CPython 3.14-backed df12 Python lint stage and ambrleaks scanner in the lint toolchain, updates documentation and ADRs to describe the five-stage gate, and repairs or strengthens code and tests to satisfy the new lint rules without suppressions (notably assertion messages, dispatch/aliasing, redirect handling, Rust availability checks, benchmarking helpers, and snapshot scanning).

Sequence diagram for the updated five-stage make lint process

sequenceDiagram
    actor Dev
    participant Makefile
    participant Ruff
    participant Interrogate
    participant PylintPyPy
    participant DF12Pylint
    participant Ambrleaks

    Dev->>Makefile: make lint
    Makefile->>Ruff: $(RUFF) check
    Ruff-->>Makefile: status
    alt Ruff failure
        Makefile-->>Dev: stop lint
    else Ruff success
        Makefile->>Interrogate: uv run interrogate --fail-under 100 cuprum
        Interrogate-->>Makefile: status
        alt Interrogate failure
            Makefile-->>Dev: stop lint
        else Interrogate success
            Makefile->>PylintPyPy: $(PYLINT) $(PYLINT_TARGETS)
            PylintPyPy-->>Makefile: status
            alt PyPy Pylint failure
                Makefile-->>Dev: stop lint
            else PyPy Pylint success
                Makefile->>DF12Pylint: $(DF12_PYLINT) $(PYLINT_TARGETS)
                DF12Pylint-->>Makefile: status
                alt DF12 Pylint failure
                    Makefile-->>Dev: stop lint
                else DF12 Pylint success
                    Makefile->>Ambrleaks: $(AMBRLEAKS) cuprum/unittests tests
                    Ambrleaks-->>Makefile: status
                    alt Ambrleaks failure
                        Makefile-->>Dev: stop lint
                    else Ambrleaks success
                        Makefile-->>Dev: run Rust and Whitaker lint stages
                    end
                end
            end
        end
    end

Loading

File-Level Changes

Change	Details	Files
Extend the lint toolchain with a CPython 3.14 df12 Pylint pass and ambrleaks snapshot scanner, sharing a local Pylint cache.	Add PYLint cache and environment variables so both Pylint passes share .cache/pylint. Define df12 plugin and CPython 3.14 configuration (DF12_PYTHON_LINTS_REF, DF12_PYTHON, DF12_PYLINT_MESSAGES, DF12_PYLINT). Add AMBRLEAKS command wired to the df12-python-lints repository. Run df12 Pylint and ambrleaks from the lint target over existing Python lint targets and snapshot roots.	Makefile
Document the five-stage Python lint gate, df12 plugin configuration, ambrleaks policy, and coordination of tool pins.	Update developer guide to describe Ruff, interrogate, PyPy-backed Pylint, df12 Pylint under CPython 3.14, and ambrleaks as sequential lint stages with failure-handling guidance. Extend lint-related variable table with df12 and ambrleaks variables plus a shared Pylint cache, and note coupled updates for df12 dependency and tool ref. Expand episodic lint policy to include df12 messages and ambrleaks coverage, and reference ambrleaks.toml allowlists. Point canonical lint configuration to the df12 dev dependency and ambrleaks.toml allowlist file.	docs/developers-guide.md
Amend ADR-003 to record the df12 and ambrleaks additions, their configuration in pyproject and Makefile, and associated risks/benefits.	Update ADR status and decision to include df12 Pylint under CPython 3.14 and ambrleaks snapshot scanning. Describe the expanded lint target ordering (Ruff, interrogate, PyPy-backed Pylint, df12 Pylint, ambrleaks). Document that df12 is pinned as a dev dependency and ambrleaks is pinned separately, plus allowlists for deterministic path-like fixtures. Add risks about CPython 3.14 availability and keeping df12 and ambrleaks pins aligned, and benefits of df12 checks and ambrleaks coverage outside source tree.	docs/adr-003-two-tier-python-linting.md
Introduce an ambrleaks allowlist for known deterministic public base64 fixtures that look like POSIX paths.	Create ambrleaks.toml with a narrow allowlist of two snapshot values, including anchors and escaping for characters that resemble paths.	ambrleaks.toml
Strengthen assertion messages and expectations throughout behaviour, benchmark, and unit tests to meet df12 assertion/diagnostic rules.	Add explicit messages to asserts in pipeline execution, concurrency helper, context hooks, benchmark comparison, benchmark suite, stream microbenchmarks, execution runtime, structured events, builder library, env context, logging hook, Rust extension, stream fidelity, and other behaviour tests. Wrap some multi-assert checks in grouped messages or expectation-failed strings to improve diagnostics under failure. Align tests with new lint expectations around clarity of failure conditions and explicit comparison descriptions.	tests/behaviour/test_pipeline_execution.py tests/behaviour/test_concurrency_helper.py tests/behaviour/test_context_hooks.py tests/behaviour/test_benchmark_comparison_report_behaviour.py tests/behaviour/test_benchmark_suite_behaviour.py tests/behaviour/test_execution_runtime.py tests/behaviour/test_structured_events.py tests/behaviour/test_builder_library_behaviour.py tests/behaviour/test_env_context_behaviour.py tests/behaviour/test_logging_hook_behaviour.py tests/behaviour/test_rust_extension_behaviour.py tests/behaviour/test_stream_fidelity.py benchmarks/test_stream_microbenchmarks.py
Tighten urllib redirect handling and header stripping logic to be lint-compliant and compatible with both positional and keyword call contracts.	Define a typed alias for redirect_request argument tuples including HTTPMessage. Introduce _redirect_request_arguments helper that pattern-matches positional vs keyword argument forms, validates types, and normalizes them. Make _ArtifactArchiveRedirectHandler._strip_cross_origin_headers a staticmethod and update redirect_request to use normalized arguments instead of a loose *args/**kwargs pass-through. Use DF12-friendly type and match constructs and avoid bool-code confusion in HTTP status handling.	benchmarks/fetch_main_benchmark_baseline.py
Refine subprocess invocations and comments in profiling and perf tooling to make argument validation and tool sourcing explicit for lint.	Annotate subprocess.run and subprocess.Popen calls with clarifying comments for security lint rules (S603) explaining validated inputs and tool paths. Keep perf, inferno, and py-spy calls structured with explicit env and error-handling but without suppressing lint findings. Retain existing behaviour while satisfying df12 subprocess usage expectations.	benchmarks/tee_profile_profilers.py
Simplify and consolidate Rust backend availability helpers so benchmarks and library code share the same checked resolver, and validate its contract.	Make is_rust_available call _check_rust_available, assert the result is bool, and raise TypeError if the resolver violates its contract. Expand _check_rust_available docstring to describe its role as the canonical resolver for public alias and backend selection, cache semantics, and test overrides. Replace duplicate can_use_rust_backend wrappers in tee_profile_scenarios and profile_tee_hotpath with imports of cuprum.is_rust_available / can_use_rust_backend. Adjust Rust benchmark and profiling scenarios to use the unified backend availability function.	cuprum/rust.py cuprum/_backend.py benchmarks/tee_profile_scenarios.py benchmarks/profile_tee_hotpath.py
Refine JSON-serialisation and telemetry support while satisfying new type and immutability lint checks.	Rewrite _json_serializable to use structural pattern matching over mappings, sequences, primitives, and fallback types. Update telemetry adapter test handler emit method to assign a new list including the latest record (immutability/aliasing-friendly) instead of mutating in place. Clarify logging adapter behaviour while leaving public interface unchanged.	cuprum/adapters/logging_adapter.py tests/behaviour/test_telemetry_adapters.py
Adjust shell command builders, context access, pipeline dispatch hooks, backend selector API, benchmarking worker limits, and catalogue visibility to align with df12 aliasing, dispatch, and API-shape rules.	Inline _coerce_argv logic into build_argv so SafeCmd builders call the public function, aligning alias and dispatch expectations. Alias get_context directly to current_context instead of a separate function definition to simplify context access patterns. Change backend selector call to be the context manager that activates a backend, eliminating an indirection method and matching df12 dispatch style. Cap pipeline_worker iterations using a named constant _MAX_ITERATIONS and reuse it in validation logic. Have reset_pump_stream_dispatch_for_testing directly clear specific pump-test-hook attributes instead of calling configure_pump_stream_dispatch_for_testing. Change catalogue.visible_settings to return a fresh MappingProxyType wrapping a copy of internal project mapping rather than a cached proxy field.	cuprum/sh.py cuprum/context/state.py benchmarks/_tee_profile_worker_backend.py benchmarks/pipeline_worker.py cuprum/_pipeline_streams.py cuprum/catalogue.py
Clarify exception aggregation on pipeline cleanup, and retain lint-acceptable BaseExceptionGroup usage.	Adjust comments around _drain_tasks_during_cleanup to explain catching BaseException for task failures and aggregation with active_error so cleanup never masks triggering errors. Leave the BaseExceptionGroup construction logic but align commentary with df12 expectations about blind catches.	cuprum/_pipeline_internals.py
Update Python type annotations and backend name aliasing for benchmarks to be df12-compliant.	Change BackendName definition from a simple alias to a type alias declaration to match df12 style. Ensure usage sites reference BackendName consistently across benchmark modules.	benchmarks/_benchmark_types.py
Pin df12-python-lints as a dev dependency and configure Pylint py-version for Cuprum’s supported baseline in project config.	Add df12-python-lints git dependency at v0.1.0 to the dev dependency group. Set [tool.pylint.main].py-version to 3.12 to reflect the semantic baseline used by Cuprum. Keep other Pylint and Ruff configuration intact while enabling df12 plugin integration.	pyproject.toml

---

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.

[codescene-access]

No quality gates enabled for this code.

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[leynos]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.

[leynos]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.

[leynos]

@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.

[coderabbitai]

Actionable comments posted: 1

🤖 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/_backend.py`:
- Around line 90-106: Shorten the `_check_rust_available` docstring to a
single-line summary describing its purpose. Remove the redundant `Returns` and
`Notes` sections; retain cache or testing guarantees only as module-level
narrative if they are not otherwise documented.

🪄 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: 89bbec3b-9042-446b-aa10-3b5a85c7c0e0

📥 Commits

Reviewing files that changed from the base of the PR and between 45828c9 and 8bb484a.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (36)

• Makefile
• ambrleaks.toml
• benchmarks/_benchmark_types.py
• benchmarks/_tee_profile_worker_backend.py
• benchmarks/fetch_main_benchmark_baseline.py
• benchmarks/pipeline_worker.py
• benchmarks/profile_tee_hotpath.py
• benchmarks/ratchet_rust_performance.py
• benchmarks/tee_profile_profilers.py
• benchmarks/tee_profile_scenarios.py
• benchmarks/test_stream_microbenchmarks.py
• cuprum/_backend.py
• cuprum/_pipeline_internals.py
• cuprum/_pipeline_streams.py
• cuprum/adapters/logging_adapter.py
• cuprum/catalogue.py
• cuprum/context/state.py
• cuprum/rust.py
• cuprum/sh.py
• cuprum/unittests/test_context.py
• docs/adr-003-two-tier-python-linting.md
• docs/developers-guide.md
• pyproject.toml
• tests/behaviour/test_benchmark_comparison_report_behaviour.py
• tests/behaviour/test_benchmark_suite_behaviour.py
• tests/behaviour/test_builder_library_behaviour.py
• tests/behaviour/test_concurrency_helper.py
• tests/behaviour/test_context_hooks.py
• tests/behaviour/test_env_context_behaviour.py
• tests/behaviour/test_execution_runtime.py
• tests/behaviour/test_logging_hook_behaviour.py
• tests/behaviour/test_pipeline_execution.py
• tests/behaviour/test_rust_extension_behaviour.py
• tests/behaviour/test_stream_fidelity.py
• tests/behaviour/test_structured_events.py
• tests/behaviour/test_telemetry_adapters.py

🔗 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)

[leynos]

@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.

[coderabbitai]

Actionable comments posted: 5

🤖 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 `@benchmarks/fetch_main_benchmark_baseline.py`:
- Around line 72-106: Update _redirect_request_arguments to bind positional and
keyword inputs using normal Python argument-binding rules, accepting valid mixed
calls such as a positional req/fp with code, msg, headers, and newurl supplied
by keyword while still rejecting missing, duplicate, unexpected, or incorrectly
typed arguments. Preserve the returned _RedirectRequestArguments shape and add
regression coverage for mixed positional/keyword invocations.

In `@benchmarks/test_stream_microbenchmarks.py`:
- Around line 90-93: Update the assertions in the benchmark result checks around
result.ok, result.stdout, output == expected, and consumed == payload_bytes to
report bounded observed state: include result.exit_code for success failures and
expected versus actual lengths or byte counts for output and consumption
mismatches. Keep explicit assertion messages, avoid payload contents, and apply
the same diagnostics to the additional checks around consumed output.

In `@cuprum/rust.py`:
- Around line 34-37: Add regression coverage for the validation in
is_rust_available: mock _check_rust_available() to return a non-bool value and
assert that calling is_rust_available() raises TypeError. Add the unhappy-path
pytest coverage in tests/behaviour/test_rust_extension_behaviour.py while
preserving the existing valid-result and native-agreement tests.

In `@Makefile`:
- Around line 51-59: Pin the DF12 dependency consistently to the immutable
revision recorded in uv.lock: update DF12_PYTHON_LINTS_REF and the AMBRLEAKS
source in Makefile lines 51-59, and align the corresponding df12-python-lints
declaration in pyproject.toml line 20. Regenerate or update uv.lock to preserve
that same revision, while continuing to use the transitively locked pylint
dependency.

In `@tests/behaviour/test_benchmark_suite_behaviour.py`:
- Around line 127-129: Update the assertion messages in the benchmark-plan
behavior test, including then_benchmark_plan_indicates_dry_run and the checks at
the other referenced assertions, so each identifies its specific failed
condition: profile-version mismatch, forbidden “uv run python” text, missing
sys.executable, or missing CUPRUM_STREAM_BACKEND prefix. Keep the assertions and
expected values unchanged while making every diagnostic actionable.

🪄 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: 008bfeb3-3a10-4257-81ec-d096227be6a3

📥 Commits

Reviewing files that changed from the base of the PR and between 45828c9 and 8bb484a.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (36)

• Makefile
• ambrleaks.toml
• benchmarks/_benchmark_types.py
• benchmarks/_tee_profile_worker_backend.py
• benchmarks/fetch_main_benchmark_baseline.py
• benchmarks/pipeline_worker.py
• benchmarks/profile_tee_hotpath.py
• benchmarks/ratchet_rust_performance.py
• benchmarks/tee_profile_profilers.py
• benchmarks/tee_profile_scenarios.py
• benchmarks/test_stream_microbenchmarks.py
• cuprum/_backend.py
• cuprum/_pipeline_internals.py
• cuprum/_pipeline_streams.py
• cuprum/adapters/logging_adapter.py
• cuprum/catalogue.py
• cuprum/context/state.py
• cuprum/rust.py
• cuprum/sh.py
• cuprum/unittests/test_context.py
• docs/adr-003-two-tier-python-linting.md
• docs/developers-guide.md
• pyproject.toml
• tests/behaviour/test_benchmark_comparison_report_behaviour.py
• tests/behaviour/test_benchmark_suite_behaviour.py
• tests/behaviour/test_builder_library_behaviour.py
• tests/behaviour/test_concurrency_helper.py
• tests/behaviour/test_context_hooks.py
• tests/behaviour/test_env_context_behaviour.py
• tests/behaviour/test_execution_runtime.py
• tests/behaviour/test_logging_hook_behaviour.py
• tests/behaviour/test_pipeline_execution.py
• tests/behaviour/test_rust_extension_behaviour.py
• tests/behaviour/test_stream_fidelity.py
• tests/behaviour/test_structured_events.py
• tests/behaviour/test_telemetry_adapters.py

🔗 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)

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[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.

[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.

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

Makefile (1)

124-131: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Split the lint recipe.

Line 124 has seven recipe lines. This exceeds checkmake's configured maximum of
five. Extract the Python and Rust lint stages into named targets, and preserve
their current execution order.

🤖 Prompt for 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.

In `@Makefile` around lines 124 - 131, Split the lint recipe into named Python and
Rust lint targets, moving the existing Ruff, interrogate, Pylint, DF12, and
Ambleaks commands into the Python target and the Rust documentation, Clippy,
Whitaker, and spelling commands into the Rust target. Update lint to depend on
these targets in the same Python-then-Rust order, keeping each command’s
behavior unchanged and reducing the lint recipe to at most five lines.

Source: Linters/SAST tools

cuprum/unittests/test_logging_adapter_properties.py (1)

62-75: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Reduce the private-helper docstring.

Move the logging-level rationale to an inline comment if it must remain. Leave
_capturing_logger with a concise summary. Remove the Returns section.

Proposed fix

 def _capturing_logger(name: str) -> tuple[logging.Logger, _CollectingHandler]:
-    """Return a logger that captures everything, plus its handler.
-
-    The level is set explicitly rather than left at ``NOTSET``, which would
-    defer to the root logger's ``WARNING`` and make the hook skip its own
-    debug and info records — a real behaviour of the hook (it checks
-    ``isEnabledFor`` before building anything), but not the one under test
-    here.
-
-    Returns
-    -------
-    tuple[logging.Logger, _CollectingHandler]
-        The configured logger and its attached collecting handler.
-    """
+    """Return a logger and handler that capture all records for tests."""

As per path instructions, private functions and methods must use a single-line
summary. Based on learnings, private helpers should retain only narrative text
for non-obvious guarantees.

🤖 Prompt for 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.

In `@cuprum/unittests/test_logging_adapter_properties.py` around lines 62 - 75,
Reduce the _capturing_logger docstring to a single-line summary, removing the
detailed logging-level rationale and Returns section; preserve the rationale
only as an inline comment if it is still needed to explain the explicit logger
level.

Sources: Path instructions, Learnings

🤖 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/_backend.py`:
- Around line 272-275: In the exception handler around _read_backend_env(),
assign str(exc) to a local msg variable before raising, then pass msg to
ValueError while preserving the explicit from exc cause.

In `@cuprum/unittests/test_context_narrowing.py`:
- Around line 197-199: Update the single-step narrowing call immediately before
the assertion to pass parent_is_restricted=True, matching both calls used to
compute two_step. Preserve the existing comparison and ensure empty-parent
inputs retain restricted-parent semantics.

In `@Makefile`:
- Around line 55-58: Update the DF12_PYLINT command so its isolated uv run
explicitly provides pylint and the df12_python_lints plugin through immutable
--with dependencies, or reuse the locked development environment instead.
Preserve the existing Python selection, plugin loading, and enabled-message
configuration.

---

Outside diff comments:
In `@cuprum/unittests/test_logging_adapter_properties.py`:
- Around line 62-75: Reduce the _capturing_logger docstring to a single-line
summary, removing the detailed logging-level rationale and Returns section;
preserve the rationale only as an inline comment if it is still needed to
explain the explicit logger level.

In `@Makefile`:
- Around line 124-131: Split the lint recipe into named Python and Rust lint
targets, moving the existing Ruff, interrogate, Pylint, DF12, and Ambleaks
commands into the Python target and the Rust documentation, Clippy, Whitaker,
and spelling commands into the Rust target. Update lint to depend on these
targets in the same Python-then-Rust order, keeping each command’s behavior
unchanged and reducing the lint recipe to at most five lines.

🪄 Autofix

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: 15e43c2f-4611-4273-b7fa-a9e221dd8f38

📥 Commits

Reviewing files that changed from the base of the PR and between dd46fa1 and e9346c8.

📒 Files selected for processing (35)

• Makefile
• benchmarks/_github_http.py
• benchmarks/_tee_profile_worker_backend.py
• benchmarks/comparison_report.py
• benchmarks/fetch_main_benchmark_baseline.py
• benchmarks/pipeline_throughput_runner.py
• benchmarks/ratchet_ratio_extraction.py
• benchmarks/ratchet_rust_performance.py
• cuprum/_backend.py
• cuprum/_pipeline_wait.py
• cuprum/_process_lifecycle.py
• cuprum/adapters/metrics_adapter.py
• cuprum/catalogue.py
• cuprum/sh.py
• cuprum/unittests/test_benchmark_ci_ratchet.py
• cuprum/unittests/test_catalogue.py
• cuprum/unittests/test_concurrent_execution.py
• cuprum/unittests/test_context_narrowing.py
• cuprum/unittests/test_fetch_main_benchmark_baseline.py
• cuprum/unittests/test_fetch_main_benchmark_cli.py
• cuprum/unittests/test_fetch_main_benchmark_redirects.py
• cuprum/unittests/test_folded_summary.py
• cuprum/unittests/test_logging_adapter_properties.py
• cuprum/unittests/test_pipeline_output_options.py
• cuprum/unittests/test_pipeline_wait.py
• cuprum/unittests/test_rust_extension.py
• cuprum/unittests/test_rust_streams.py
• docs/debugging/debugging-plan-20260801T140750.md
• docs/developers-guide.md
• tests/behaviour/_benchmark_ratchet_support.py
• tests/behaviour/test_concurrency_helper.py
• tests/behaviour/test_stream_fidelity.py
• tests/conftest.py
• tests/helpers/maturin.py
• tests/helpers/maturin_wheel.py

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Construct the translated exception message before raising.

Set msg = str(exc) before Line 275. Pass msg to ValueError. Preserve the
explicit cause.

Proposed fix

 except ValueError as exc:
-    raise ValueError(str(exc)) from exc
+    msg = str(exc)
+    raise ValueError(msg) from exc

As per coding guidelines, construct exception messages once in a variable and
pass that object to the exception constructor.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	try:
	requested = _read_backend_env()
	except ValueError as exc:
	raise ValueError(str(exc)) from exc
	try:
	requested = _read_backend_env()
	except ValueError as exc:
	msg = str(exc)
	raise ValueError(msg) from exc

🤖 Prompt for 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.

In `@cuprum/_backend.py` around lines 272 - 275, In the exception handler around
_read_backend_env(), assign str(exc) to a local msg variable before raising,
then pass msg to ValueError while preserving the explicit from exc cause.

Source: Coding guidelines

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Preserve restricted-parent semantics in the single-step comparison.

Line 195 omits parent_is_restricted=True, but Lines 193-194 set it for both
two-step calls. If parent is empty and first & second is non-empty,
two_step is empty while single_step becomes non-empty. The property then
fails despite equivalent narrowing semantics.

Proposed fix

-    single_step = _narrow_allowlist(parent, first & second)
+    single_step = _narrow_allowlist(
+        parent,
+        first & second,
+        parent_is_restricted=True,
+    )

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	assert two_step == single_step, (
	"two narrowing steps should equal the combined intersection"
	)
	single_step = _narrow_allowlist(
	parent,
	first & second,
	parent_is_restricted=True,
	)
	assert two_step == single_step, (
	"two narrowing steps should equal the combined intersection"
	)

🤖 Prompt for 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.

In `@cuprum/unittests/test_context_narrowing.py` around lines 197 - 199, Update
the single-step narrowing call immediately before the assertion to pass
parent_is_restricted=True, matching both calls used to compute two_step.
Preserve the existing comparison and ensure empty-parent inputs retain
restricted-parent semantics.

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

uv run --isolated --python 3.14 python -c '
import importlib.util
print(importlib.util.find_spec("df12_python_lints"))
'

uv run --isolated --python 3.14 pylint --version

Repository: leynos/cuprum

Length of output: 191

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'Makefile excerpt:\n'
if [ -f Makefile ]; then
  nl -ba Makefile | sed -n '45,70p'
else
  echo 'Makefile not found'
fi

printf '\nRelevant pyproject/uv files:\n'
git ls-files | grep -E '(^|/)(pyproject\.toml|uv\.lock|Makefile)$' | while read -r f; do
  echo "--- $f"
  sed -n '1,220p' "$f"
done

Repository: leynos/cuprum

Length of output: 209

---

🌐 Web query:

uv run --isolated tool dependencies package management

💡 Result:

The --isolated flag in uv run enforces strict environment isolation by forcing the creation of a fresh, ephemeral virtual environment, bypassing the reuse of the standard project environment [1][2][3]. Key behaviors of uv run --isolated include: Environment Isolation: While uv typically reuses the project's virtual environment (usually located at.venv) for performance, --isolated forces a fresh environment to be generated [1][2][3]. This is useful for testing or ensuring that a command cannot import packages that are not explicitly declared as dependencies [4]. Project Handling: Even when using --isolated, the project itself is still installed into the environment as an editable dependency [1][2][3]. If you need to avoid discovering the project or workspace entirely, the --no-project flag is used instead [1][2]. Layering: If you combine --isolated with flags like --with or --with-requirements, those additional dependencies are layered into a second environment to maintain the required structure [1][2][3]. In summary, --isolated is a tool for strict dependency verification and environment cleanliness, ensuring that commands run in a predictable, freshly-synced state without relying on potentially stale or impure project environments [1][2][4]. You can also control this behavior via the UV_ISOLATED environment variable [1][2][3].

Citations:

• 1: https://docs.astral.sh/uv/reference/cli/
• 2: https://mintlify.wiki/astral-sh/uv/cli/run
• 3: https://docs.rs/uv-cli/latest/uv_cli/struct.RunArgs.html
• 4: Add --isolated support to uv run astral-sh/uv#5471

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'Makefile excerpt:\n'
if [ -f Makefile ]; then
  awk 'NR>=45 && NR<=70 {printf "%5d  %s\n", NR, $0;}' Makefile
else
  echo 'Makefile not found'
fi

printf '\nRelevant dependency/config files:\n'
git ls-files | grep -E '(^|/)(pyproject\.toml|uv\.lock|Makefile)$' | while read -r f; do
  echo "--- $f"
  awk '{printf "%5d  %s\n", NR, $0;}' "$f"
done

Repository: leynos/cuprum

Length of output: 50370

---

Provide the missing isolated tool dependencies.

DF12_PYLINT runs uv run --isolated, and pylint plus df12_python_lints are not supplied for that command. Add the required tools as immutable --with dependencies or run against the locked dev environment.

🤖 Prompt for 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.

In `@Makefile` around lines 55 - 58, Update the DF12_PYLINT command so its
isolated uv run explicitly provides pylint and the df12_python_lints plugin
through immutable --with dependencies, or reuse the locked development
environment instead. Preserve the existing Python selection, plugin loading, and
enabled-message configuration.

[codescene-access]

Code Health Improved (1 files improve in Code Health)

Our agent can fix these. Install it.

Gates Passed
6 Quality Gates Passed

View Improvements

File	Code Health Impact	Categories Improved
fetch_main_benchmark_baseline.py	9.69 → 10.00	Complex Method

Absence of Expected Change Pattern

• cuprum/tests/helpers/maturin.py is usually changed with: cuprum/cuprum/unittests/test_maturin_build.py

Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.