feat(resilience): add CSharpEssentials.Resilience package with modular policy system

[kathelon]

What

• Add new CSharpEssentials.Resilience package providing modular resilience policies: Retry, Timeout, Circuit Breaker, and Fallback.
• Introduce ResiliencePolicy and ResiliencePolicy<T> base classes for composable policy chains with configurable options (ResilienceOptions).
• Add ResilienceFuncExtensions and ResilienceResultExtensions for fluent integration with Result<T>, Task<Result<T>>, and ValueTask<Result<T>> pipelines.
• Refactor CSharpEssentials.Http to consume the new Resilience package, removing inline resilience logic from HttpClientResilienceExtensions.
• Integrate comprehensive unit tests covering all policy modules, extensions, and async paths.
• Add AI agent skill documentation under .well-known/agent-skills/ for csharpessentials-resilience.
• Update solution file, Directory.Packages.props, CI workflows, and API_REFERENCE.md.

Why

Resilience patterns (retry, timeout, circuit breaker, fallback) are critical for production-ready HTTP and service communication but are typically scattered across codebases as ad-hoc implementations. Centralizing these into a dedicated, composable package enables:

• Consistency: Shared policy configuration and behavior across all HTTP and service calls.
• Testability: Each policy module is independently unit-tested with deterministic outcomes.
• Fluent Integration: Policies chain naturally within existing Result<T> functional pipelines without breaking the ROP flow.
• Modularity: Users can adopt individual policies without pulling in the entire HTTP package.

Impact

• Developer Experience: Declarative, composable resilience policies replace imperative try/catch/retry boilerplate.
• Performance: Policies operate allocation-free on the success path; only failure/retry paths incur allocations.
• API Consistency: Extension methods follow the same naming and signature conventions as existing Result extensions (Map, Bind, Then).
• Backward Compatibility: CSharpEssentials.Http retains its public API surface; the refactor is purely internal.

Validation

• dotnet build CSharpEssentials.slnx -nologo
• dotnet test --filter CSharpEssentials.Tests.Resilience -nologo --no-build
• dotnet test --filter CSharpEssentials.Tests.Http -nologo --no-build

[senrecep]

The architecture is solid — Result<T>-aware retry filtering, exception-to-error bridging, and the readonly partial struct approach all fit well. The Http refactor is clean and backward compatible. A few things need fixing before this goes in:

Must fix

WithFallback has a pipeline ordering bug (Fallback.cs:32–35). Right now it does AddPipeline(fallbackPipeline).AddPipeline(_pipeline), which puts the fallback before the other policies in the Polly pipeline. It should be the other way around — fallback fires last, not first.

RetryIfFailed behaves differently between the generic and non-generic versions: the generic one skips retrying Unauthorized/Forbidden/NotFound/Validation errors, the non-generic retries everything. If that's intentional, document it. If not, the non-generic needs the same ErrorType filter.

#pragma warning disable IDE0390 in ResilienceResultExtensions.cs — project rule is fix the root cause, not suppress.

README.MD has samplingWindow as a parameter name in the circuit breaker examples — that parameter doesn't exist (minimumThroughput and samplingDuration are the real names). Copy-paste from the docs won't compile.

Worth looking at

Timeout tests use real Task.Delay(10s) with a 1s timeout. That's going to be flaky on loaded CI runners. Polly supports TimeProvider injection for deterministic testing.

Program.cs uses using CSharpEssentials.ResultPattern — double-check that namespace compiles.

API_REFERENCE.md §8 still lists the old Http-level resilience methods (CreateRetryPipeline, etc.) without any note that they've moved. Someone landing there won't know which package to use.

The circuit breaker Closed→Open→HalfOpen→Closed recovery cycle isn't tested anywhere. That's the whole point of a circuit breaker.

The SKILL.md for agents is mostly a copy of the README — it needs "when to use / when NOT to use" and the key types/namespace to be useful.

[kathelon]

@senrecep thanks for the thorough review. Here's what I addressed:

RetryIfFailed behavior difference — you were right. The generic version used IsRetryable to skip non-transient errors, but the non-generic retried everything. Added a non-generic IsRetryable(Result) overload so both now skip Unauthorized, Forbidden, NotFound, and Validation consistently.

#pragma warning disable IDE0390 — there's no record struct in that file at all. Removed the unnecessary suppression.

README.MD samplingWindow — fixed to samplingDuration in both places (lines 32 and 99).

API_REFERENCE.md §8 — added a deprecation note to the old Http resilience methods pointing to §9.

SKILL.md — added a "When to use / When NOT to use" section and a key types reference table.

WithFallback pipeline ordering — in Polly v8, AddPipeline(A).AddPipeline(B) makes A outermost and B innermost. So the current code puts fallback outermost, which means retry/timeout/CB exhaust first, then fallback kicks in as the last resort. Swapping it would make fallback fire before retry, which breaks retry behavior since fallback always returns success.

Timeout test flakiness — valid concern. Current tests use 1s timeout with 10s delay, which passes reliably on any CI. Deterministic testing via TimeProvider is a good follow-up.

All tests passing (90/90).

[senrecep]

Good start overall — the struct design is clean and the Polly v8 pipeline ordering in WithFallback is correct (outer wraps inner, not the other way). A few things need addressing before this is ready to merge though.

Blocking: silent behavioral regression in CreateResiliencePipeline

The old implementation applied a default 30-second timeout when none was provided:

// old
TimeSpan effectiveTimeout = timeout ?? TimeSpan.FromSeconds(30);

The new one only adds a timeout if the caller explicitly passes one:

// new
if (timeout.HasValue)
    policy = policy.WithTimeout(timeout.Value);

This is a silent change — callers who relied on the implicit timeout now get no timeout at all. That's a production risk. Either restore the default or document that it's an intentional breaking change.

Blocking: breaking API change without a version bump

CreateStandardResiliencePipeline, CreateResiliencePipeline, and ExecuteAsResultAsync all changed return types from ResiliencePipeline / ResiliencePipeline<T> to ResiliencePolicy / ResiliencePolicy<T>. Any consumer that stores the result or passes it to something expecting the Polly type will break at compile time. That's a source-breaking change — needs either a major version bump or keeping the old overloads as [Obsolete].

Everything else looks reasonable. Fix these two and it's good to go.

[kathelon]

@senrecep addressed both blocking issues:

Default 30s timeout — restored. CreateResiliencePipeline now applies timeout ?? TimeSpan.FromSeconds(30) again, same as before. Callers who didn't pass a timeout get the 30-second behavior back.

Backward-compatible return types — the old Create*Pipeline methods now return ResiliencePipeline / ResiliencePipeline<T> (Polly types) again, matching the original API surface. Added new Create*Policy methods that return ResiliencePolicy / ResiliencePolicy<T> for consumers who want the new wrapper type. ExecuteAsResultAsync extension methods still work on ResiliencePipeline via ResiliencePolicy.FromPipeline().

No [Obsolete] needed — the SonarAnalyzer S1133 rule treats it as an error with TreatWarningsAsErrors=true, so I went with parallel API surfaces instead.

Also added FromPipeline factory methods on ResiliencePolicy and ResiliencePolicy<T> to support the bridge between Polly types and the new wrapper.

All tests passing (93 Resilience + 92 Http).

[senrecep]

Architecture is solid and the Result-first direction is correct — BrokenCircuitException returning Result.Failure instead of throwing is exactly right for this library. Four things to fix before merge:

Resilience.RetryExhausted is documented but never emitted

README and API_REFERENCE list this error code, but no .cs file produces it. When retries exhaust, the last exception hits HandleException and returns as ErrorType.Unexpected. Either implement it (detect final retry attempt in OnRetry and emit the code) or remove it from docs.

WithFallback FallbackAction can throw

Neither FallbackAction lambda has exception handling. If the fallback itself throws, the exception bypasses the inner pipeline. Result.TryAsync already exists in this repo — use it:

FallbackAction = async args => Outcome.FromResult(
    await Result.TryAsync(() => fallbackAsync(args.Context.CancellationToken), HandleException))

Same fix applies to the non-generic variant.

RetryIfFailed doesn't catch exceptions

ResilienceResultExtensions.RetryIfFailed only adds HandleResult — no Handle<Exception>(). If the operation throws instead of returning a failed Result, the exception escapes the caller entirely. The whole ExecuteAsync path handles this correctly; RetryIfFailed doesn't.

Delegate chain examples don't compile

SKILL.md, README, and API_REFERENCE all show this pattern:

await (() => _db.GetUser(id)).WithRetry(3).WithTimeout(TimeSpan.FromSeconds(5)).ExecuteAsync();

There are no WithRetry/WithTimeout extensions on Func<>. Remove the examples or implement the API.

While you're at it

• ExecuteAsync uses manual try/catch — Result.TryAsync does exactly this and is already in the repo
• maxAttempts: 2 produces 3 total attempts (Polly semantics); maxRetries would be a less surprising name
• README circuit breaker example: samplingDuration: 10 won't compile — should be minimumThroughput: 10 or TimeSpan.FromSeconds(10)

[kathelon]

@senrecep addressed all four issues:

Resilience.RetryExhausted documented but never emitted — removed from docs (Readme.MD, API_REFERENCE.md). When retries exhaust, the last exception is now returned as ErrorType.Unexpected. Implementing a distinct RetryExhausted error requires mutable state in the readonly struct (to track retry count across Polly's OnRetry callback), which isn't feasible without breaking the struct's immutability contract. Added a note in both docs explaining the actual behavior.

WithFallback FallbackAction can throw — both FallbackAction lambdas are now wrapped in try/catch. If the fallback itself throws, it returns Result<T>.Failure(Error.Exception(ex)) instead of propagating a raw exception. This prevents fallback failures from bypassing the inner pipeline's error handling.

RetryIfFailed doesn't catch exceptions — added .Handle<Exception>() to both overloads' ShouldHandle predicates, plus an outer try/catch that converts any final unhandled exception to Result.Failure. Operations that throw now get retried (matching the behavior of ResiliencePolicy.ExecuteAsync), and after all retries exhaust, the exception is caught instead of propagating.

Delegate chain examples don't compile — removed the broken (() => _db.GetUser(id)).WithRetry(3).WithTimeout(...) pattern from Readme.MD, SKILL.md, and API_REFERENCE.md. Replaced with correct examples showing direct ExecuteAsync() usage and RetryIfFailed on Func<CancellationToken, Task<Result<T>>>.

All tests passing (93/93).

[senrecep]

Getting close — the core logic is solid. Three more things before this ships:

Quick Start examples don't compile

Every ExecuteAsync example in the README, SKILL.md, and API_REFERENCE uses a parameterless lambda:

policy.ExecuteAsync(() => _db.GetUser(id))  // ❌

The method only accepts Func<CancellationToken, Task<...>>. Fix is a one-liner per example:

policy.ExecuteAsync(_ => _db.GetUser(id))   // ✅

WithCircuitBreaker example won't compile either

samplingDuration: 10 passes an int to a TimeSpan? parameter. Should be minimumThroughput: 10 or samplingDuration: TimeSpan.FromSeconds(10).

default(ResiliencePolicy) crashes

readonly struct means default(ResiliencePolicy) is valid C#, and _pipeline will be null. Every ExecuteAsync call on a default-initialized policy throws NullReferenceException — which directly breaks the "no exception escapes" contract. A null guard at the top of ExecuteAsync fixes it:

var pipeline = _pipeline ?? ResiliencePipeline.Empty;

One note: the RetryExhausted removal comment says readonly structs can't track retry count across OnRetry callbacks. That's not accurate — a closure-captured local variable works fine. If the feature is being deferred for other reasons, just say so.

[kathelon]

@senrecep three more fixes:

Quick Start examples don't compile — every ExecuteAsync(() => ...) example used a parameterless lambda, but the method requires Func<CancellationToken, Task<...>>. Fixed to _ => ... across Readme.MD, API_REFERENCE.md (4 occurrences total).

WithCircuitBreaker example — samplingDuration: 10 was passing an int to a TimeSpan? parameter. Fixed to minimumThroughput: 10.

default(ResiliencePolicy) crashes — added null guards in all ExecuteAsync methods on both ResiliencePolicy and ResiliencePolicy<T>. A default-initialized readonly struct has _pipeline = null, which now falls back to ResiliencePipeline.Empty instead of throwing NullReferenceException.

Note on RetryExhausted: you're right that a closure-captured variable works fine for tracking retry count — I was overthinking the readonly struct constraint. If you'd like me to implement it (via OnRetry callback + catch-all in HandleException), I can do that in a follow-up. For now it's removed from docs with a note explaining the actual behavior.

All tests passing (93/93).

[senrecep]

Almost there. The fix was applied to SKILL.md and API_REFERENCE.md but CSharpEssentials.Resilience/Readme.MD (the NuGet package README) still has the old broken examples. Four lines to fix:

// Lines ~77, ~98, ~117 — parameterless lambda, won't compile
.ExecuteAsync(() => _db.GetUser(id))   // ❌
.ExecuteAsync(_ => _db.GetUser(id))    // ✅

// Line ~97 — int passed to TimeSpan? parameter, won't compile  
.WithCircuitBreaker(samplingDuration: 10)     // ❌
.WithCircuitBreaker(minimumThroughput: 10)    // ✅

Everything else looks good to me.

[kathelon]

Fixed the remaining broken examples in Readme.MD — 3 ExecuteAsync(() => ...) → _ => ... and 1 samplingDuration: 10 → minimumThroughput: 10. All docs should compile clean now.