feat: add distributed lock lease pattern

[JerrettDavis]

Closes #483.

Summary

• Adds a Distributed Lock / Lease runtime with expiring leases, contention, renewal, release, snapshots, and fluent builder configuration.
• Adds [GenerateDistributedLock], generator diagnostics, TinyBDD coverage, docs, example, IServiceCollection import, and BenchmarkDotNet scenario coverage.
• Updates production-readiness catalogs, benchmark matrices, README/docs pattern tables, and generator attribute coverage.

Validation

• dotnet build PatternKit.slnx --configuration Release --no-restore -p:UseSharedCompilation=false
• dotnet test test\PatternKit.Tests\PatternKit.Tests.csproj --configuration Release --framework net8.0 --no-build -p:UseSharedCompilation=false
• dotnet test test\PatternKit.Generators.Tests\PatternKit.Generators.Tests.csproj --configuration Release --framework net8.0 --no-build -p:UseSharedCompilation=false
• dotnet test test\PatternKit.Examples.Tests\PatternKit.Examples.Tests.csproj --configuration Release --framework net8.0 --no-build -p:UseSharedCompilation=false
• dotnet test test\PatternKit.Hosting.Extensions.Tests\PatternKit.Hosting.Extensions.Tests.csproj --configuration Release --framework net8.0 --no-build -p:UseSharedCompilation=false
• dotnet format PatternKit.slnx --verify-no-changes --verbosity minimal
• git diff --check
• docfx metadata docs\docfx.json; docfx build docs\docfx.json

[github-actions]

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

This PR introduces a new Distributed Lock / Lease pattern across the PatternKit stack (runtime + generator + example), and wires it into the production-readiness catalogs, documentation, and benchmark coverage infrastructure.

Changes:

• Adds an in-memory lease-based DistributedLock<TKey> runtime with acquire/renew/release, expiry, snapshots, and builder configuration.
• Adds [GenerateDistributedLock] + an incremental generator that emits configured DistributedLock<TKey> factory methods, with diagnostics and test coverage.
• Adds a DI-importable “Order Allocation” example plus docs, catalog entries, and BenchmarkDotNet scenario coverage/matrix updates.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
test/PatternKit.Tests/Cloud/DistributedLocks/DistributedLockTests.cs	New TinyBDD coverage for the runtime lock/lease behavior (acquire/contend/renew/release/validation).
test/PatternKit.Generators.Tests/DistributedLockGeneratorTests.cs	Generator tests for valid output, invalid declarations diagnostics, nested hosts, and malformed key types.
test/PatternKit.Generators.Tests/AbstractionsAttributeCoverageTests.cs	Adds [GenerateDistributedLock] to attribute coverage + validates defaults.
test/PatternKit.Examples.Tests/ProductionReadiness/PatternKitPatternCatalogTests.cs	Updates production catalog expectations for the new pattern count/name.
test/PatternKit.Examples.Tests/ProductionReadiness/PatternKitBenchmarkCoverageTests.cs	Updates expected totals and adds humanization mapping for the new benchmark class name.
test/PatternKit.Examples.Tests/DistributedLockDemo/OrderAllocationDistributedLockDemoTests.cs	Verifies fluent vs generated example behavior and DI importability.
src/PatternKit.Generators/DistributedLocks/DistributedLockGenerator.cs	New incremental generator for distributed lock factories + diagnostics.
src/PatternKit.Generators/AnalyzerReleases.Unshipped.md	Registers new diagnostic IDs PKDLOCK001/PKDLOCK002.
src/PatternKit.Generators.Abstractions/DistributedLocks/DistributedLockAttributes.cs	Adds GenerateDistributedLockAttribute abstraction API.
src/PatternKit.Examples/ProductionReadiness/PatternKitPatternCatalog.cs	Adds the new pattern entry with source/test/docs paths.
src/PatternKit.Examples/ProductionReadiness/PatternKitExampleCatalog.cs	Adds the new example descriptor entry for production-readiness validation.
src/PatternKit.Examples/DistributedLockDemo/OrderAllocationDistributedLockDemo.cs	New DI-ready example demonstrating fluent + generated paths.
src/PatternKit.Examples/DependencyInjection/PatternKitExampleServiceCollectionExtensions.cs	Integrates the new example into the aggregate AddPatternKitExamples() registrations.
src/PatternKit.Core/Cloud/DistributedLocks/DistributedLock.cs	New runtime implementation and related record/result/state types.
README.md	Updates pattern counts/tables and adds benchmark rows (Pending values).
docs/patterns/toc.yml	Adds the new pattern page to the patterns TOC.
docs/patterns/cloud/distributed-lock-lease.md	New pattern documentation page.
docs/index.md	Updates pattern counts/tables to include the new pattern.
docs/guides/benchmark-results.md	Updates matrix totals and adds rows/coverage entries for the new benchmarks and generator.
docs/generators/toc.yml	Adds generator doc link to the generators TOC.
docs/generators/index.md	Adds distributed lock generator to the generator index table.
docs/generators/distributed-lock.md	New distributed lock generator documentation page.
docs/examples/toc.yml	Adds the new example page to the examples TOC.
docs/examples/order-allocation-distributed-lock.md	New example documentation page.
docs/examples/index.md	Adds the new example to the examples index list.
benchmarks/PatternKit.Benchmarks/Cloud/DistributedLockBenchmarks.cs	Adds benchmark scenarios for fluent vs generated construction/execution.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

Test Results

    12 files      12 suites   11m 33s ⏱️
 4 176 tests  4 176 ✅ 0 💤 0 ❌
12 965 runs  12 965 ✅ 0 💤 0 ❌

Results for commit 4c8cb9f.

♻️ This comment has been updated with latest results.

[github-actions]

🔍 PR Validation Results

Version: ``

✅ Validation Steps

• Build solution
• Run tests
• Build documentation
• Dry-run NuGet packaging

📊 Artifacts

Dry-run artifacts have been uploaded and will be available for 7 days.

---

This comment was automatically generated by the PR validation workflow.

[codecov]

Codecov Report

❌ Patch coverage is 99.66997% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 97.42%. Comparing base (aa92ac9) to head (4c8cb9f).

Files with missing lines	Patch %	Lines
...ators/DistributedLocks/DistributedLockGenerator.cs	99.09%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #498      +/-   ##
==========================================
+ Coverage   97.41%   97.42%   +0.01%     
==========================================
  Files         603      607       +4     
  Lines       49238    49540     +302     
  Branches     3184       34    -3150     
==========================================
+ Hits        47963    48263     +300     
- Misses       1275     1277       +2     

Flag	Coverage Δ
unittests	97.42% <99.66%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 27 out of 27 changed files in this pull request and generated 5 comments.

[github-actions]

Code Coverage

Summary
  Generated on: 06/01/2026 - 13:29:56
  Coverage date: 06/01/2026 - 13:28:02 - 06/01/2026 - 13:29:45
  Parser: MultiReport (8x Cobertura)
  Assemblies: 5
  Classes: 1800
  Files: 607
  Line coverage: 97.4%
  Covered lines: 48261
  Uncovered lines: 1279
  Coverable lines: 49540
  Total lines: 105079
  Branch coverage: 84.3% (15463 of 18328)
  Covered branches: 15463
  Total branches: 18328
  Method coverage: 97.3% (9419 of 9677)
  Full method coverage: 91.6% (8869 of 9677)
  Covered methods: 9419
  Fully covered methods: 8869
  Total methods: 9677

PatternKit.Core                                                                                                     96.2%
  PatternKit.Application.ActivityTracking.ActivityGateState                                                          100%
  PatternKit.Application.ActivityTracking.ActivityLease                                                              100%
  PatternKit.Application.ActivityTracking.ActivityRecord                                                             100%
  PatternKit.Application.ActivityTracking.ActivityTracker                                                            100%
  PatternKit.Application.Aggregates.AggregateCommandHandler<T1, T2, T3>                                              100%
  PatternKit.Application.Aggregates.AggregateCommandResult<T>                                                        100%
  PatternKit.Application.Aggregates.AggregateRoot<T1, T2>                                                            100%
  PatternKit.Application.AntiCorruption.AntiCorruptionLayer<T1, T2>                                                 90.4%
  PatternKit.Application.AntiCorruption.AntiCorruptionResult<T>                                                      100%
  PatternKit.Application.AuditLog.AuditLogAppendResult<T>                                                           85.7%
  PatternKit.Application.AuditLog.InMemoryAuditLog<T1, T2>                                                          95.4%
  PatternKit.Application.BoundedContexts.BoundedContextAdapter                                                       100%
  PatternKit.Application.BoundedContexts.BoundedContextCapability                                                   83.3%
  PatternKit.Application.BoundedContexts.BoundedContextDescriptor                                                   95.4%
  PatternKit.Application.ContextMaps.ContextMapDescriptor                                                           96.8%
  PatternKit.Application.ContextMaps.ContextMapRelationship                                                          100%
  PatternKit.Application.DataMapping.DataMapper<T1, T2>                                                             94.6%
  PatternKit.Application.DataMapping.DataMapperError                                                                  90%
  PatternKit.Application.DataMapping.DataMapperResult<T>                                                            84.6%
  PatternKit.Application.DomainEvents.DomainEventDispatcher<T>                                                      95.4%
  PatternKit.Application.DomainEvents.DomainEventDispatchResult                                                      100%
  PatternKit.Application.DomainServices.DomainServiceOperation<T1, T2>                                               100%
  PatternKit.Application.DomainServices.DomainServiceRegistry<T1, T2>                                                100%
  PatternKit.Application.EventSourcing.EventStoreAppendResult                                                        100%
  PatternKit.Application.EventSourcing.InMemoryEventStore<T1, T2>                                                   97.9%
  PatternKit.Application.EventSourcing.StoredEvent<T1, T2>                                                            80%
  PatternKit.Application.EventualConsistency.EventualConsistencyEvaluation<T>                                       92.3%
  PatternKit.Application.EventualConsistency.EventualConsistencyMonitor<T>                                          97.2%
  PatternKit.Application.EventualConsistency.EventualConsistencyMonitorState<T>                                      100%
  PatternKit.Application.EventualConsistency.EventualConsistencyWatermarks<T>                                       96.7%
  PatternKit.Application.FeatureToggles.FeatureToggleDecision                                                       87.5%
  PatternKit.Application.FeatureToggles.FeatureToggleRule<T>                                                         100%
  PatternKit.Application.FeatureToggles.FeatureToggleSet<T>                                                         96.9%
  PatternKit.Application.IdentityMap.IdentityMap<T1, T2>                                                             100%
  PatternKit.Application.IdentityMap.IdentityMapResult<T>                                                           92.8%
  PatternKit.Application.LazyLoading.LazyLoad<T>                                                                    98.1%
  PatternKit.Application.LazyLoading.LazyLoadResult<T>                                                               100%
  PatternKit.Application.ManualTaskGates.ManualTaskGate<T>                                                          98.5%