Property tests for subprocess timeout & fail-fast reducers (#75)

[leynos]

Summary

The subprocess timeout handler and the pipeline fail-fast cleanup are temporal and branch-heavy, with a risk of inconsistent timeout payloads, non-idempotent cleanup, and double-termination scheduling — and no isolated seam for their decisions (#75). This extracts two pure reducers and property-tests them without process state or a clock.

Seams

_resolve_timeout_payload(exc, _TimeoutFallback) (cuprum._subprocess_timeout) — the timeout-payload seam:

• a _SubprocessTimeoutError carries a payload captured on the stream-timeout path, used verbatim;
• a bare TimeoutError is resolved from a _TimeoutFallback (configured timeout, captured stdout/stderr, injected exit-time clock reading);
• either branch yields a concrete timeout, so downstream TimeoutExpired reporting is consistent.

_handle_subprocess_timeout now calls it and keeps the exit-event emit and the raise.

_stages_to_terminate(failure_index, done) (cuprum._process_lifecycle) — the fail-fast selection: every stage except the failed one and any already-finished stage, each at most once. _terminate_pipeline_remaining_stages drives it (keeping the strict-length zip for scheduling).

Tests

cuprum/unittests/test_subprocess_timeout_reducers.py (Hypothesis) proves the three #75 goals:

• Timeout payload consistency — the carried payload wins and never consults the fallback; a bare timeout resolves exactly from the fallback (timeout/clock/stdout/stderr); a missing configured timeout is an internal invariant error.
• No double-termination scheduling — the selection is exactly the running, non-failed stages, unique and ordered, never the failure index.
• Idempotent cleanup — once the selected stages settle, a second pass selects nothing.

Validation

Full gates green: make check-fmt, make lint (ruff, interrogate 100%, pylint 10.00/10), make test (825 passed / 58 skipped incl. existing timeout & pipeline behaviour suites; Rust nextest 57/57). Wheel-manifest snapshot regenerated.

Closes #75

🤖 Generated with Claude Code

Summary by Sourcery

Extract pure reducers for subprocess timeout payload resolution and fail-fast pipeline termination, and property-test their behaviour for consistency and idempotence.

New Features:

• Introduce a _TimeoutFallback data structure and _resolve_timeout_payload reducer to unify subprocess timeout payload resolution.
• Introduce a _stages_to_terminate reducer to select pipeline stages for termination after fail-fast.

Enhancements:

• Refactor _handle_subprocess_timeout to delegate payload resolution to a pure reducer for consistent timeout reporting.
• Refactor _terminate_pipeline_remaining_stages to use a precomputed termination target set, avoiding double-scheduling and ensuring idempotent cleanup.

Tests:

• Add Hypothesis-based property tests for subprocess timeout payload resolution and fail-fast termination selection reducers.

[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

[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: 59fe2771-9ddb-4604-b406-4f96be733eee

📥 Commits

Reviewing files that changed from the base of the PR and between fbd355d and 340cf62.

📒 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

• Extracted two pure reducers: _resolve_timeout_payload (normalises timeout details from either a carried _SubprocessTimeoutError payload or a _TimeoutFallback) and _stages_to_terminate (deterministically selects unfinished, non-failed pipeline stage indices to terminate after fail-fast).
• Refactored existing timeout handling and fail-fast cleanup to delegate to the reducers while preserving observable behaviour (event emission, exception raising, and strict scheduling semantics), including preventing duplicate termination.
• Added Hypothesis property tests for timeout payload consistency (carried vs fallback, and invariant error when no configured timeout exists) and for fail-fast stage selection ordering/idempotency.
• Added bounded CrossHair verification (five PEP 316 contracts) for both reducers using check_states with MessageType.CONFIRMED, plus import-time CrossHair availability handling via cuprum/unittests/_crosshair_support.py.
• Updated documentation and diagrams in docs/cuprum-design.md and expanded docs/developers-guide.md with the verification approach (Hypothesis + CrossHair), invariants, bounds, and compatibility/skip conditions.
• Updated the wheel-manifest snapshot to include the new CrossHair and reducer test modules.

Walkthrough

Refactor timeout payload normalisation and fail-fast stage selection into dedicated helpers. Route timeout handling through resolved details, select only running pipeline stages for termination, and add Hypothesis and CrossHair verification with documentation and wheel snapshot updates.

Changes

Timeout and fail-fast lifecycle reducers

Layer / File(s)	Summary
Normalize timeout payloads cuprum/_subprocess_timeout.py	Introduce _TimeoutFallback and _resolve_timeout_payload, route timeout handling through resolved details, and export the new symbols.
Select remaining pipeline stages cuprum/_process_lifecycle.py	Extract stage termination selection and use it to build fail-fast termination tasks for running, non-failed stages.
Validate reducer behaviour cuprum/unittests/test_subprocess_timeout_reducers.py, cuprum/unittests/__snapshots__/test_maturin_build.ambr	Add Hypothesis properties for timeout resolution, invariant enforcement, stage selection, and idempotent cleanup; record the new test modules in the wheel snapshot.
Verify bounded symbolic contracts cuprum/unittests/_crosshair_support.py, cuprum/unittests/test_subprocess_timeout_reducers_crosshair.py	Add shared CrossHair availability handling and symbolic checks for timeout payload resolution and fail-fast stage selection.
Document flows and verification docs/cuprum-design.md, docs/developers-guide.md	Add accessible lifecycle diagrams and document bounded Hypothesis and CrossHair verification commands and skip behaviour.

### Sequence Diagram(s)

sequenceDiagram
  participant TimeoutHandler
  participant TimeoutResolver
  participant PipelineCleanup
  participant StageSelector
  TimeoutHandler->>TimeoutResolver: resolve timeout details
  TimeoutResolver-->>TimeoutHandler: concrete payload
  PipelineCleanup->>StageSelector: select unfinished stages
  StageSelector-->>PipelineCleanup: termination targets

Loading

Possibly related PRs

• leynos/cuprum#158: Refactors the same timeout-translation path in cuprum/_subprocess_timeout.py.

Suggested labels: Issue

Suggested reviewers: codescene-delta-analysis, codescene-access

Poem

Gather timeout fields in line,
Let failed stages mark the sign.
Test each path both broad and bright,
CrossHair checks the states at night—
Clean pipelines hum by design.

🚥 Pre-merge checks | ✅ 20

✅ Passed checks (20 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title matches the PR focus on property tests for the timeout and fail-fast reducers and includes the linked issue.
Description check	✅ Passed	The description directly explains the reducer extraction, property tests, and CrossHair verification in scope.
Linked Issues check	✅ Passed	The changes satisfy #75 by proving timeout payload consistency, idempotent cleanup, and no double-termination scheduling.
Out of Scope Changes check	✅ Passed	The documentation, snapshot, and CrossHair support changes all support the reducer verification work and stay in scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Testing (Overall)	✅ Passed	PASS: The new Hypothesis and CrossHair tests directly exercise both reducers and cover carried payloads, fallback resolution, invariant errors, uniqueness, ordering and idempotence.
User-Facing Documentation	✅ Passed	PASS: The PR only extracts private reducers and adds tests/docs; docs/users-guide.md already covers the observable timeout and fail-fast behaviour.
Developer Documentation	✅ Passed	Document the new reducers and CrossHair helper in the developer guide and design doc; no roadmap or execplan item required for this work.
Module-Level Documentation	✅ Passed	Approve it: every touched Python module has a top-level docstring stating its purpose and, where needed, its relation to the timeout/fail-fast reducers.
Testing (Unit And Behavioural)	✅ Passed	PASS: the new unit/property tests cover reducer edge cases and invariants, while existing public run() and pipeline tests still exercise the observable boundaries.
Testing (Property / Proof)	✅ Passed	Hypothesis tests and bounded CrossHair contracts cover the new timeout and fail-fast invariants, and the docs now recommend both for these reducers.
Testing (Compile-Time / Ui)	✅ Passed	No Rust/TypeScript compile-time path changed, and the wheel snapshot test is focused, normalised, and backed by new Hypothesis/CrossHair reducer tests.
Unit Architecture	✅ Passed	PASS: the PR extracts pure reducers for timeout selection and fail-fast termination; side-effects stay in command handlers, with explicit fallback/ctx inputs and property tests.
Domain Architecture	✅ Passed	PASS: the new reducers stay in internal subprocess/pipeline modules, translate timeout and stage state only, and add no domain-to-infrastructure boundary leak.
Observability	✅ Passed	Refactor only extracted pure reducers; existing start/exit observation emits remain intact and no new logging, metrics, tracing, or alerts were introduced.
Security And Privacy	✅ Passed	Only docs diagram text changed; no secrets, auth, permission, injection, or privacy-sensitive data was added.
Performance And Resource Use	✅ Passed	Keep the new reducers linear and bounded; the only extra collections are small, fail-fast-path sets/lists, and the tests use finite symbolic domains.
Concurrency And State	✅ Passed	Reducers are pure/frozen, no new shared mutable state was added, and termination tasks are created then awaited with gather; tests cover ordering and idempotence.
Architectural Complexity And Maintainability	✅ Passed	The reducers are narrow, immediately used, and remove branchy logic without adding hidden layers or speculative indirection.
Rust Compiler Lint Integrity	✅ Passed	PASS: the PR’s symmetric diff touches only Python/docs files; no Rust source, lint suppressions, or clone changes were introduced.

📋 Issue Planner

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

View plan used: #75

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch python-subprocess-timeout-tests

---

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

[sourcery-ai]

Reviewer's Guide

Extracts two pure reducer helpers for subprocess timeout payload resolution and pipeline fail-fast termination selection, updates the timeout handler and termination logic to use them, and adds Hypothesis-based property tests to validate timeout payload consistency, no double-termination, and idempotent cleanup.

Sequence diagram for updated subprocess timeout handling

sequenceDiagram
    participant Caller
    participant _handle_subprocess_timeout
    participant _resolve_timeout_payload
    participant _emit_exit_event
    participant _raise_timeout_expired
    participant _get_exit_code

    Caller->>_handle_subprocess_timeout: exc, ctx
    _handle_subprocess_timeout->>_resolve_timeout_payload: exc, _TimeoutFallback
    _resolve_timeout_payload-->>_handle_subprocess_timeout: _SubprocessTimeoutDetails payload
    _handle_subprocess_timeout->>_get_exit_code: ctx.process
    _get_exit_code-->>_handle_subprocess_timeout: exit_code
    _handle_subprocess_timeout->>_emit_exit_event: _SubprocessExitEvent
    _handle_subprocess_timeout->>_raise_timeout_expired: _TimeoutContext, exc
    _raise_timeout_expired-->>Caller: TimeoutExpired (exception)

Loading

Sequence diagram for updated fail-fast pipeline termination selection

sequenceDiagram
    participant Caller
    participant _terminate_pipeline_remaining_stages
    participant _stages_to_terminate
    participant asyncio_create_task as asyncio.create_task
    participant _terminate_process_via_wait_task
    participant asyncio_gather as asyncio.gather

    Caller->>_terminate_pipeline_remaining_stages: processes, wait_tasks, failure_index, cancel_grace
    _terminate_pipeline_remaining_stages->>_stages_to_terminate: failure_index, [wait_task.done()]
    _stages_to_terminate-->>_terminate_pipeline_remaining_stages: list[int] targets
    loop for each idx in targets
        _terminate_pipeline_remaining_stages->>asyncio_create_task: _terminate_process_via_wait_task(process, wait_task, cancel_grace)
        asyncio_create_task->>_terminate_process_via_wait_task: process, wait_task, cancel_grace
    end
    _terminate_pipeline_remaining_stages->>asyncio_gather: termination_tasks
    asyncio_gather-->>Caller: termination completed

Loading

File-Level Changes

Change	Details	Files
Introduce a pure resolver for subprocess timeout payloads and refactor timeout handling to use it.	Add the frozen dataclass _TimeoutFallback to hold configured timeout, captured stdout/stderr, and an injected exit-time clock value used for bare TimeoutError resolution. Implement _resolve_timeout_payload to map either a _SubprocessTimeoutError (using its carried payload) or a bare TimeoutError (using _TimeoutFallback plus _require_timeout) into a _SubprocessTimeoutDetails instance. Refactor _handle_subprocess_timeout to delegate payload computation to _resolve_timeout_payload, using a _TimeoutFallback built from the execution context and time.perf_counter(), then emit the exit event and raise TimeoutExpired using the resolved payload fields. Export _TimeoutFallback and _resolve_timeout_payload in the module’s all list.	cuprum/_subprocess_timeout.py
Introduce a pure fail-fast stage selection helper and adjust pipeline termination logic to use it.	Add _stages_to_terminate, which returns indices of stages to terminate after fail-fast by filtering out the failed stage and any stages already marked done, ensuring each selected index appears at most once. Refactor _terminate_pipeline_remaining_stages to compute a target index set from _stages_to_terminate and then create termination tasks only for those indices while preserving the strict zip over processes and wait_tasks. Preserve idempotent cleanup semantics by basing selection solely on the done flags snapshot and never rescheduling already-finished stages.	cuprum/_process_lifecycle.py
Add property-based tests for the new reducers and update snapshot metadata.	Create cuprum/unittests/test_subprocess_timeout_reducers.py with Hypothesis tests that prove: carried _SubprocessTimeoutError payloads are used verbatim and ignore fallbacks, bare TimeoutError payloads are built solely from _TimeoutFallback and require a configured timeout, and fail-fast selection via _stages_to_terminate returns exactly the running, non-failed stages, uniquely and in order, and is idempotent over settled stages. Regenerate or adjust the maturin build snapshot file to account for the new tests or distribution metadata changes.	cuprum/unittests/test_subprocess_timeout_reducers.py cuprum/unittests/__snapshots__/test_maturin_build.ambr

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#75	Introduce a testable seam for subprocess timeout handling (around _handle_subprocess_timeout) and add property-based (Hypothesis) tests to verify timeout payload consistency.	✅
#75	Introduce a testable seam for pipeline fail-fast termination (around _terminate_pipeline_remaining_stages) and add property-based (Hypothesis) tests to verify idempotent cleanup and no double-termination scheduling.	✅
#75	Apply CrossHair verification to the extracted transition data / reducers involved in timeout and fail-fast lifecycle handling.	❌	The PR adds pure reducers (_resolve_timeout_payload, _stages_to_terminate) and Hypothesis property tests for them, but there is no use of CrossHair or any static/semantic verification tooling in the changes.

Possibly linked issues

• Property-based tests for _handle_subprocess_timeout and _terminate_pipeline_remaining_stages #75: The PR implements property-based tests and reducer extractions for timeout and fail-fast lifecycle logic exactly as requested.

---

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.

[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

🤖 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/_subprocess_timeout.py`:
- Around line 149-176: Update _resolve_timeout_payload to use structural
match/case for the timeout variants instead of isinstance(). Keep the
_SubprocessTimeoutError case first, preserving its captured payload fields, then
handle the bare TimeoutError using fallback and _require_timeout.

In `@cuprum/unittests/test_subprocess_timeout_reducers.py`:
- Around line 34-35: Rename the module-level Hypothesis strategies
_finite_floats and _optional_text to private UPPER_SNAKE_CASE names, and update
every reference to use the new names consistently.
- Line 67: Update the assertions in the affected tests, including the
payload/details comparison and the ranges at the referenced locations, to
include concise descriptive messages using the existing invariant each assertion
verifies. Preserve the assertion conditions while replacing every bare assert
with an assert that supplies a failure message, so Hypothesis counterexamples
identify the violated invariant.

🪄 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: f3e2f866-1342-4433-8d31-270c6185e12d

📥 Commits

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

📒 Files selected for processing (4)

• cuprum/_process_lifecycle.py
• cuprum/_subprocess_timeout.py
• cuprum/unittests/__snapshots__/test_maturin_build.ambr
• cuprum/unittests/test_subprocess_timeout_reducers.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 Have the following failed checks now been resolved?

If further work is required, please provide an AI agent prompt for the remaining work to be done to address these failures.

Do not treat warnings as optional or aspirational. Where a change is out of scope for this PR, propose a GitHub issue unless one exists already. (Treat documentation and validation coverage as in scope).

#75 Apply CrossHair verification to the extracted transition data / reducers involved in timeout and fail-fast lifecycle handling. ❌ The PR adds pure reducers (_resolve_timeout_payload, _stages_to_terminate) and Hypothesis property tests for them, but there is no use of CrossHair or any static/semantic verification tooling in the changes.

[pandalump]

Completed the CrossHair verification requirement for #75 in 25a4509. The existing Hypothesis module is untouched — this adds symbolic verification alongside it, not instead of it.

Contracts

cuprum/unittests/test_subprocess_timeout_reducers_crosshair.py adds five PEP 316 contracts, executed through check_states and required to return MessageType.CONFIRMED:

_resolve_timeout_payload

Contract	Invariant
carried_payload	a carried _SubprocessTimeoutError returns its own timeout, stdout, stderr, and exit time verbatim
fallback_payload	a bare TimeoutError with a configured timeout returns the fallback's four fields exactly
missing_timeout_raises	a bare TimeoutError with configured_timeout is None raises _SubprocessInvariantError

The independence requirement is enforced structurally rather than asserted: the fallback in the carried contract holds different values and a None configured timeout, so a resolver that consulted it would either return a wrong field or raise.

_stages_to_terminate

Contract	Invariant
selection_well_formed	every index in range, unique, ordered; none equals failure_index; every one has done[idx] is False; and the result equals exactly the unfinished non-failed set
selection_idempotent	after marking the selected stages done, a second invocation returns []

The checks actually verify

I mutation-checked rather than trusting five green ticks. Both mutants yield POST_FAIL instead of CONFIRMED:

• making the carried branch read fallback.stdout → carried_payload fails;
• dropping the failed-stage exclusion from the selection → selection_well_formed fails.

Deliberate bounds

Kept small and finite so CrossHair exhausts the space rather than returning CANNOT_CONFIRM:

• at most three stages, with failure_index constrained to a valid index by precondition;
• the per-stage done flags encoded as a single bounded integer bitmask rather than a symbolic list of symbolic booleans — this is the change that makes the space enumerable;
• three-value enumerations for times and for text (including None) instead of unrestricted floats and strings. The reducers only ever copy these, so representative values suffice; what matters is that carried and fallback values stay distinguishable, which the enumerations preserve.

Automated, not just documented

The module matches the cuprum/unittests/test_*.py glob in the Makefile's PYTEST_TARGETS, so make test collects and runs it — I verified the module appears in the make test output rather than assuming it. check_states demands CONFIRMED, so an available-but-unconfirmed result (CANNOT_CONFIRM) or a refuted postcondition fails the run; neither is downgraded to a skip or warning. Availability uses the shared _crosshair_support.py probe, which degrades to a skip only for a missing dependency (ImportError) or an interpreter the tracer cannot handle (TraceException), matching the existing 3.15 policy. On this interpreter all five report PASSED, not SKIPPED.

Note: _crosshair_support.py here is byte-identical to the copy on #243's branch, so an add/add merge of the two PRs resolves cleanly.

Validation

Command	Outcome
uv run pytest -q cuprum/unittests/test_subprocess_timeout_reducers.py	5 passed (Hypothesis, unchanged)
uv run pytest -q cuprum/unittests/test_subprocess_timeout_reducers_crosshair.py	5 passed, all CONFIRMED
uv run crosshair check ... --analysis_kind=PEP316	exit 0, no counterexamples
make check-fmt	pass
make lint	pass (ruff, interrogate 100%, pylint 10.00/10, clippy)
make typecheck	pass (ty clean)
make test	pass — 765 passed / 47 skipped, Rust nextest 57/57, CrossHair module executed
make markdownlint / make nixie	pass

The wheel-manifest snapshot was regenerated for the two new files under cuprum/. Documentation of the verified invariants, both commands, and the bounds is in docs/developers-guide.md.

Leaving #75 open until this is reviewed and merged, per the instruction to close it only once the requirement is demonstrably satisfied.

[pandalump]

All three findings verified against current code and fixed in c773b57. None were stale.

1. Structural match/case in _resolve_timeout_payload

Valid, and worth noting why: the code this reducer was extracted from — _handle_subprocess_timeout before this branch — already used a structural match/case for exactly this dispatch. My extraction quietly replaced it with isinstance, so this restores the established idiom rather than introducing a new one.

match exc:
    case _SubprocessTimeoutError(
        timeout=timeout,
        stdout=stdout,
        stderr=stderr,
        exited_at=exited_at,
    ):
        return _SubprocessTimeoutDetails(...)
    case _:
        return _SubprocessTimeoutDetails(
            timeout=_require_timeout(fallback.configured_timeout, exc),
            ...
        )

The _SubprocessTimeoutError case comes first and binds its captured fields by pattern, as asked.

One deliberate deviation: I used case _ rather than case TimeoutError() for the second arm. Because each arm returns, a non-matching input would fall off the end and implicitly return None, violating the declared -> _SubprocessTimeoutDetails. The catch-all keeps the function total. (The original could use case TimeoutError() safely because it assigned locals and fell through to shared code rather than returning.)

Behaviour is unchanged, and I confirmed that rather than assuming it: the CrossHair contract still refutes a mutant that makes the carried branch read fallback.stdout, reporting POST_FAIL instead of CONFIRMED.

2. Strategy naming

Valid. _finite_floats and _optional_text were lowercase against the convention every other property module in cuprum/unittests follows — _LINES, _SEGMENTS, _ABS_PATHS, _COMPRESSIONS, _OUTPUT_OPTIONS, _CONSUMER_OUTCOME. Renamed to _FINITE_FLOATS and _OPTIONAL_TEXT, with all references updated.

(The strategies in the adjacent CrossHair module, _TIMES and _TEXTS, already matched the convention.)

3. Assertion messages

Valid — the module had ten bare assertions. Every one now names the invariant it verifies, so a Hypothesis counterexample identifies the violated property rather than only the values that broke it. For example:

assert payload == details, (
    "a carried _SubprocessTimeoutError payload must be returned verbatim, "
    "with no field taken from the fallback"
)
assert failure_index not in result, (
    "the failed stage owns its own exit and must never be terminated"
)

That covers the carried-payload comparison, the four fallback field assertions, the four selection assertions, and the idempotence assertion. grep for bare asserts in the file now returns zero.

Validation

Command	Outcome
uv run pytest cuprum/unittests/test_subprocess_timeout_reducers.py	5 passed
uv run pytest cuprum/unittests/test_subprocess_timeout_reducers_crosshair.py	5 passed, all CONFIRMED
uv run pytest cuprum/unittests/test_subprocess_timeout.py	4 passed (existing timeout suite intact)
make check-fmt	pass
make lint	pass (ruff, interrogate 100%, pylint 10.00/10, clippy)
make typecheck	pass (ty clean — this is what the total-match point above protects)
make test	pass — Rust nextest 57/57, full Python suite green
make markdownlint / make nixie	pass

[pandalump]

@coderabbitai I have self-validated the three Inconclusive pre-merge rows, since each was marked inconclusive for want of evidence rather than for a suspected defect. Evidence below.

Module-Level Documentation. Every module the PR adds or changes opens with a docstring, and the repository's interrogate gate enforces this at 100%:

cuprum/_subprocess_timeout.py                                   module docstring: yes
cuprum/_process_lifecycle.py                                    module docstring: yes
cuprum/unittests/test_subprocess_timeout_reducers.py            module docstring: yes
cuprum/unittests/test_subprocess_timeout_reducers_crosshair.py  module docstring: yes
cuprum/unittests/_crosshair_support.py                          module docstring: yes

RESULT: PASSED (minimum: 100.0%, actual: 100.0%)

Unit Architecture. The extracted reducers are pure functions in the modules that own the behaviour, not a new layer, and every touched module stays well inside the repository's 400-line cap (AGENTS.md L25-27):

261  cuprum/_subprocess_timeout.py
283  cuprum/_process_lifecycle.py
330  cuprum/unittests/test_subprocess_timeout_reducers_crosshair.py
182  cuprum/unittests/test_subprocess_timeout_reducers.py

Performance And Resource Use. Both reducers are pure, allocation-light and called once per event, not per byte or per poll — _stages_to_terminate once per pipeline failure (_process_lifecycle.py:268) and _resolve_timeout_payload once per timeout (_subprocess_timeout.py:191). Measured:

_stages_to_terminate(stages=  3):   0.28 us/call   O(n) single pass, one list
_stages_to_terminate(stages= 10):   0.52 us/call
_stages_to_terminate(stages=100):   3.43 us/call
_resolve_timeout_payload:           1.59 us/call   one frozen dataclass, no I/O

Against a subprocess spawn or a timeout wait these are far below the noise floor, and the extraction replaced inline branches of the same complexity, so there is no regression to measure against.

[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' '== Repository module-size guidance =='
rg -n -C 3 '400.{0,20}(line|Line)|module.{0,40}400' AGENTS.md || true

printf '%s\n' '== File line counts and first non-empty lines =='
for f in \
  cuprum/_subprocess_timeout.py \
  cuprum/_process_lifecycle.py \
  cuprum/unittests/test_subprocess_timeout_reducers.py \
  cuprum/unittests/test_subprocess_timeout_reducers_crosshair.py \
  cuprum/unittests/_crosshair_support.py
do
  printf '\n%s\n' "-- $f"
  wc -l "$f"
  sed -n '1,12p' "$f"
done

printf '%s\n' '== Structural map of changed implementation and test modules =='
ast-grep outline \
  cuprum/_subprocess_timeout.py \
  cuprum/_process_lifecycle.py \
  cuprum/unittests/test_subprocess_timeout_reducers.py \
  cuprum/unittests/test_subprocess_timeout_reducers_crosshair.py \
  cuprum/unittests/_crosshair_support.py \
  --items all

printf '%s\n' '== Reducer declarations and all in-repository call contexts =='
rg -n -C 8 \
  'def (_resolve_timeout_payload|_stages_to_terminate)\b|_resolve_timeout_payload\(|_stages_to_terminate\(' \
  cuprum

printf '%s\n' '== Reducer implementations and handler contexts =='
rg -n -C 20 \
  'def _resolve_timeout_payload\b|def _handle_subprocess_timeout\b|def _stages_to_terminate\b|def _terminate_pipeline_remaining_stages\b' \
  cuprum/_subprocess_timeout.py cuprum/_process_lifecycle.py

Length of output: 40391

---

@pandalump: Clear all three previously inconclusive rows.

• Module-level documentation: Verify this as satisfied. Each listed changed module begins with a module docstring.
• Unit architecture: Verify this as satisfied. The reducers remain in their behaviour-owning modules, and the inspected files range from 83 to 330 lines—each below the stated 400-line threshold.
• Performance and resource use: Verify the design conclusion. _resolve_timeout_payload only selects/copies fields and constructs one payload; _stages_to_terminate is a single O(n) list-comprehension pass. Their only production call sites run once per timeout and once per pipeline fail-fast cleanup respectively, rather than inside a polling or byte-processing loop.

Treat the reported microbenchmark figures as self-reported runtime measurements; static inspection independently confirms the allocation-light, non-I/O, linear/event-level characteristics underlying them.

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

[codescene-access]

No quality gates enabled for this code.

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