Runtime: Work Graph builder + wave execution

[cursor]

Summary

Implements the Runtime module for Fork–Join Work Graph (#309): consumers can register steps with WorkGraphBuilder<TContext>, Build() validates the DAG, and IWorkGraph<TContext>.RunAsync executes topological waves with same-wave concurrency and fail-fast cancellation.

Related Issue

Closes #309

Claim note: this automation could not add agent-working / assignee via the GitHub token (issues write 403); treating this PR as the claim for #309.

Solution module

• Runtime (DesignPatterns/)
• Diagnostics (DesignPatterns.Diagnostics/)
• SourceGenerators (DesignPatterns.SourceGenerators/)
• Analyzers (DesignPatterns.Analyzers/ + DesignPatterns.CodeFixes/)
• DependencyInjection (DesignPatterns.Extensions.DependencyInjection/)
• Package (DesignPatterns.Package/)
• Docs / Repository (README, docs/, .github/, AGENTS.md, build/)

Type of change

• Bug fix
• Feature
• Source generator / diagnostic / CodeFix change
• Refactor (no behavior change)
• Docs / repo metadata only

Test plan

• dotnet test tests/DesignPatterns.Tests/DesignPatterns.Tests.csproj -c Release --filter FullyQualifiedName~WorkGraphTests (14 passed)
• dotnet build DesignPatterns/DesignPatterns.csproj -c Release (netstandard2.0 + net8.0, 0 warnings)
• Full ./build.ps1 --target Ci --configuration Release (SDK installed ad-hoc in this environment; targeted Runtime tests + dual-TFM build verified)
• Sibling samples (API not yet consumed by Samples; Samples ticket is separate)

Breaking changes

• None
• Yes — describe migration steps (APIs may still be pre-stable):

Checklist

• This PR touches only one solution module (see AGENTS.md)
• Commit messages are in English (no AI/agent tooling mentions in commits)
• PR description is English only — no AI/agent/Cursor tool attribution, no auto-generated summary blocks (e.g. CURSOR_SUMMARY, "Made with …")
• No version bumps, tags, releases, or NuGet publish steps included unless explicitly requested
• Public API / diagnostic / generated code changes are documented if user-visible

Documentation checklist

• Design Doc updated if API / diagnostic / implementation changed
• User-facing docs synced (separate PRs if multi-repo)
• No documentation changes needed

Design Doc / ROADMAP / CHANGELOG land in Docs ticket #312 after Diagnostics (#310) and SourceGenerators (#311).

  

---

Note

Medium Risk
New public concurrency API with shared-context semantics; behavior is covered by tests but callers must avoid unsynchronized same-wave writes.

Overview
Adds a fork–join work graph runtime under DesignPatterns.Behavioral: consumers register steps with string ids and DependsOn edges via WorkGraphBuilder<TContext>, Build() validates the DAG (empty graph, duplicate ids, bad dependencies, cycles) and materializes topological waves, and IWorkGraph<TContext>.RunAsync runs each wave—steps in the same wave concurrently on one shared context, later waves after predecessors finish.

Execution is fail-fast: the first step failure cancels in-flight peers through a linked CancellationToken and rethrows the real exception (not peer cancel noise). Caller cancellation is honored. WorkGraphAttribute / WorkStepAttribute (plus generic attribute on .NET 7+) are included for upcoming source-generator wiring but are not used to build graphs in this PR.

Tests: WorkGraphTests covers validation, diamond ordering, fail-fast peer cancel, and caller cancellation.

^{Reviewed by Cursor Bugbot for commit 5b9d798. Configure here.}

[cursor]

Left a non-blocking comment: Cursor Bugbot passed with no findings, but GitHub blocked bot self-approval on this PR. Reviewer Skymly was assigned for human approval.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}