feat(api): compile-time void fallback safety

[thomhurst]

Fifth round of pre-release API review cleanups. The +semver:minor prefix follows #176–#181.

1. Compile-time void-fallback safety

Untyped Fallback(...) now changes the chain's static type from Shield to VoidShield. The chain still starts from Shield; the type changes only when a void fallback is added, and every later fluent call preserves VoidShield.

VoidShield exposes only void Execute/ExecuteAsync/context overloads. It cannot be assigned to Shield, lifted with For<TResult>(), wrapped into a typed shield, or passed to mixed Shield.Compose(...). Wrap(...) propagates the void-only state in either direction. Result-producing recovery remains Shield.For<TResult>().Fallback(...).

ShieldBuilder.Fallback(...) returns VoidShield; later handling clauses use VoidShieldBuilder. PartitionedVoidShield<TKey> and void-aware DI registry, rate-limiter adapter, testing descriptor, and state-snapshot APIs carry the type state through integrations. The former KEV005 runtime-risk analyzer is removed because these invalid uses now fail C# compilation.

Coverage includes compile-success and compile-failure contracts, all 12 public void execution forms, cancellation/deferred completion/exception identity/null guards, chaining and builder immutability, both wrap directions, partition retention, DI coexistence, rate-limiter adapters, analyzer recognition, reflection surface checks, and API baselines.

2. WhenResultIsNull() / OrResultIsNull()

New ShieldResultExtensions methods constrained with where TResult : class?. They use the existing default(TResult) predicate but render as [when null result]. WhenResultIsDefault/OrResultIsDefault remain for value types and generic code.

3. KEV010 (Info)

Reports WhenResultIsDefault/OrResultIsDefault on a known non-nullable value type, where 0, false, or an empty struct may be a legitimate result. Nullable<T> and type parameters are skipped. The new null-result clauses participate in KEV007/KEV009 handling-clause analysis.

4. KEV009 severity

No code change: KEV009 was already DiagnosticSeverity.Info, documented and tested as such.

5. Wrap and Compose

Verified and documented that outer.Wrap(inner) and Shield.Compose(outer, inner) have identical ordering, clause sealing, naming, and TimeProvider precedence. Mixed static composition with a VoidShield is intentionally rejected because C# cannot conditionally change a params Shield[] return type; use Wrap(...), which preserves VoidShield.

6. Backoff.Custom clamping

The retry path already clamps negative and over-limit delays and applies MaxDelay. XML documentation now states that behavior, with an added end-to-end MaxDelay regression test.

7. Execution docs ordering

No change needed: the docs already lead with the simple execution overload and reserve explicit state for zero-closure hot paths.

Validation

• dotnet build Kevlar.slnx -c Release: clean, 0 warnings/errors, including net10.0 and netstandard2.0 API baselines.
• 1,068 compiled tests passed: Kevlar.Tests 791; Analyzers 75; Integration 118; Testing 33; RateLimiting 20; Chaos 23; NetStandard 5; Allocation 3.
• 118 package-based C# documentation snippets compiled and executed.
• Docusaurus production build passed.

Branch note

api-review-cleanups-4 belonged to merged PR #180, so this PR uses api-review-cleanups-5.

https://claude.ai/code/session_01KAPqkMyQnM44sRnoYQ6hmg

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

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 615589f4-ccb8-415f-95af-b4c402f9b87f

---

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