feat: add lazy load pattern

[JerrettDavis]

Closes #487.

Summary

• Adds the Lazy Load runtime primitive with caching, TTL, invalidation, cancellation, and single-flight loading.
• Adds source-generator attributes, generator diagnostics, TinyBDD runtime/generator/example/hosting coverage, and BenchmarkDotNet coverage.
• Adds IServiceCollection integrations, production-readiness catalog entries, README/docs tables, and user guide pages.

Validation

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

[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

Adds a new Lazy Load application-architecture pattern to PatternKit, including a runtime primitive (LazyLoad<TValue>), a source generator ([GenerateLazyLoad] + LazyLoadGenerator), DI registration helpers, an importable example, docs/catalog updates, and benchmark coverage wiring.

Changes:

• Introduces LazyLoad<TValue> runtime API with caching, TTL, invalidation, cancellation, and single-flight behavior.
• Adds [GenerateLazyLoad] attribute + Roslyn incremental generator with diagnostics and generator test coverage.
• Integrates Lazy Load into hosting extensions, production-readiness catalogs, docs/TOCs, examples, and BenchmarkDotNet coverage matrix.

Reviewed changes

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

Show a summary per file

File	Description
test/PatternKit.Tests/Application/LazyLoading/LazyLoadTests.cs	Adds TinyBDD runtime coverage for caching, TTL, invalidation, and cancellation behaviors.
test/PatternKit.Hosting.Extensions.Tests/DependencyInjection/PatternKitServiceCollectionExtensionsTests.cs	Extends hosting extension tests to validate AddPatternKitLazyLoad registration and argument validation.
test/PatternKit.Generators.Tests/LazyLoadGeneratorTests.cs	Adds generator scenarios covering source output and diagnostics.
test/PatternKit.Examples.Tests/ProductionReadiness/PatternKitPatternCatalogTests.cs	Updates catalog assertions to include the new Lazy Load pattern.
test/PatternKit.Examples.Tests/ProductionReadiness/PatternKitBenchmarkCoverageTests.cs	Updates expected benchmark coverage matrix totals for the new pattern/routes.
test/PatternKit.Examples.Tests/LazyLoadDemo/CustomerProfileLazyLoadDemoTests.cs	Adds example validation for fluent + generated lazy load and DI import.
src/PatternKit.Hosting.Extensions/DependencyInjection/PatternKitServiceCollectionExtensions.cs	Adds AddPatternKitLazyLoad<TValue> DI registration helper.
src/PatternKit.Generators/LazyLoading/LazyLoadGenerator.cs	Introduces the Lazy Load incremental generator + PKLL diagnostics.
src/PatternKit.Generators/AnalyzerReleases.Unshipped.md	Registers new PKLL analyzer IDs in release notes.
src/PatternKit.Generators.Abstractions/LazyLoading/LazyLoadAttributes.cs	Adds [GenerateLazyLoad] attribute for source generation.
src/PatternKit.Examples/ProductionReadiness/PatternKitPatternCatalog.cs	Adds Lazy Load to the production-readiness pattern catalog.
src/PatternKit.Examples/ProductionReadiness/PatternKitHostingIntegrationCatalog.cs	Adds Lazy Load hosting integration entry for AddPatternKitLazyLoad<TValue>.
src/PatternKit.Examples/ProductionReadiness/PatternKitExampleCatalog.cs	Adds the new importable Lazy Load example to the example catalog.
src/PatternKit.Examples/LazyLoadDemo/CustomerProfileLazyLoadDemo.cs	Adds a real-world example demonstrating fluent + generated lazy load and DI composition.
src/PatternKit.Examples/DependencyInjection/PatternKitExampleServiceCollectionExtensions.cs	Wires the Lazy Load example into the examples DI registration surface.
src/PatternKit.Core/Application/LazyLoading/LazyLoad.cs	Adds the core runtime primitive (LazyLoad<TValue>) and result type.
README.md	Updates pattern counts/tables to include Lazy Load.
docs/patterns/toc.yml	Adds Lazy Load to the patterns TOC.
docs/patterns/application/lazy-load.md	Adds the Lazy Load pattern guide page.
docs/index.md	Updates pattern counts/tables on the docs landing page.
docs/guides/hosting-extensions.md	Documents the new AddPatternKitLazyLoad<TValue> hosting extension.
docs/guides/benchmark-results.md	Extends benchmark results/coverage matrix to include Lazy Load.
docs/generators/toc.yml	Adds Lazy Load to the generators TOC.
docs/generators/lazy-load.md	Adds generator documentation and diagnostics list for Lazy Load.
docs/generators/index.md	Adds Lazy Load to the generator index tables and examples.
docs/examples/toc.yml	Adds the new Lazy Load example to the examples TOC.
docs/examples/index.md	Adds Lazy Load example summary to the examples landing page.
docs/examples/customer-profile-lazy-load.md	Adds the Lazy Load demo documentation page.
benchmarks/PatternKit.Benchmarks/Application/LazyLoadBenchmarks.cs	Adds BenchmarkDotNet coverage for fluent vs generated lazy load 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 46s ⏱️
 4 135 tests  4 135 ✅ 0 💤 0 ❌
12 836 runs  12 836 ✅ 0 💤 0 ❌

Results for commit eee67c8.

♻️ This comment has been updated with latest results.

[codecov]

Codecov Report

❌ Patch coverage is 95.03817% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.40%. Comparing base (c6c36d7) to head (eee67c8).

Files with missing lines	Patch %	Lines
...ernKit.Generators/LazyLoading/LazyLoadGenerator.cs	91.47%	11 Missing ⚠️
...atternKit.Core/Application/LazyLoading/LazyLoad.cs	98.46%	1 Missing ⚠️
...amples/LazyLoadDemo/CustomerProfileLazyLoadDemo.cs	95.23%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #495      +/-   ##
==========================================
- Coverage   97.41%   97.40%   -0.02%     
==========================================
  Files         591      595       +4     
  Lines       48386    48648     +262     
  Branches     3124       34    -3090     
==========================================
+ Hits        47137    47384     +247     
- Misses       1249     1264      +15     

Flag	Coverage Δ
unittests	97.40% <95.03%> (-0.02%)	⬇️

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.

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

[github-actions]

Code Coverage

Summary
  Generated on: 06/01/2026 - 09:08:52
  Coverage date: 06/01/2026 - 09:07:06 - 06/01/2026 - 09:08:41
  Parser: MultiReport (8x Cobertura)
  Assemblies: 5
  Classes: 1759
  Files: 595
  Line coverage: 97.3%
  Covered lines: 47382
  Uncovered lines: 1266
  Coverable lines: 48648
  Total lines: 103376
  Branch coverage: 84.3% (15164 of 17972)
  Covered branches: 15164
  Total branches: 17972
  Method coverage: 97.2% (9219 of 9477)
  Full method coverage: 91.5% (8675 of 9477)
  Covered methods: 9219
  Fully covered methods: 8675
  Total methods: 9477

PatternKit.Core                                                                                                     96.1%
  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%