fix(hedging): preserve composition cancellation

[thomhurst]

Summary

• define exact retry × hedge attempt scopes and maximum multiplication in both strategy orders
• distinguish total timeout outside hedging from independent per-fork timeouts inside hedging
• preserve the parent cancellation token when hedge-fork cleanup would otherwise surface a disposed linked token
• document winner, unhandled failure, caller cancellation, and loser-timeout semantics

Closes #21

Validation

• dotnet build Kevlar.slnx -c Release --no-incremental
• dotnet run --project tests/Kevlar.Tests -c Release --no-build -- --timeout 5m (365 passed; 21 consecutive runs)
• dotnet run --project tests/Kevlar.IntegrationTests -c Release --no-build -- --timeout 5m (16 passed)
• dotnet run --project tests/Kevlar.Analyzers.Tests -c Release --no-build -- --timeout 5m (19 passed)
• dotnet run --project tests/Kevlar.NetStandard.Tests -c Release --no-build -- --timeout 5m (1 passed)
• npm --prefix docs run build

[coderabbitai]

Warning

Review limit reached

@thomhurst, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 35 seconds

Limit details: You’ve used all 10 included reviews currently available.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3e35202a-5fcc-49f8-9bd2-fef25a663796

📥 Commits

Reviewing files that changed from the base of the PR and between 0e18e77 and 1c976eb.

📒 Files selected for processing (3)

• docs/docs/composition.md
• src/Kevlar/Strategies/Hedging/HedgingStrategy.cs
• tests/Kevlar.Tests/RetryHedgeTimeoutCompositionTests.cs

---

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

[greptile-apps]

Greptile Summary

The PR preserves caller-cancellation identity across disposed linked hedge tokens and documents composition behavior for retry, hedging, and timeout strategies.

• Normalizes canceled hedge outcomes to the requested parent cancellation token.
• Documents retry-by-hedge attempt multiplication and total versus per-fork timeout scopes.
• Adds composition tests covering attempt counts, winner and cancellation behavior, and timeout callbacks.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete blocking or independently actionable non-blocking issues identified.

The cancellation normalization is limited to cases where the parent token is already requested, preserves the original exception as context, and aligns with the tested and documented composition semantics.

Important Files Changed

Filename	Overview
src/Kevlar/Strategies/Hedging/HedgingStrategy.cs	Normalizes completed cancellation outcomes to the requested parent token while retaining the original exception as the inner exception.
tests/Kevlar.Tests/RetryHedgeTimeoutCompositionTests.cs	Adds focused coverage for retry/hedge multiplication, cancellation, winner cleanup, and total versus per-attempt timeout behavior.
docs/docs/composition.md	Documents composition ordering, maximum attempt multiplication, and timeout scope semantics consistently with the implementation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Strategy composition] --> B[Retry outside Hedge]
    A --> C[Hedge outside Retry]
    A --> D[Timeout outside Hedge]
    A --> E[Hedge outside Timeout]
    B --> B1[r + 1 hedge groups]
    B1 --> B2[Up to h attempts per group]
    C --> C1[Up to h hedge attempts]
    C1 --> C2[r + 1 invocations per attempt]
    D --> D1[One shared total timeout budget]
    E --> E1[Independent timeout budget per fork]
    B2 --> F[Maximum r + 1 times h invocations]
    C2 --> F

Loading

_{Reviews (1): Last reviewed commit: "fix(hedging): preserve parent cancellati..." | Re-trigger Greptile}