GFramework/ai-plan/public/traces/cqrs-cache-docs-hardening-trace.md

CQRS Cache And Docs Hardening Trace

2026-04-17

Stage: Discovery

• Read AGENTS.md and .ai/environment/tools.ai.yaml before selecting repository tools.
• Confirmed README.md quick-install guidance omits GeWuYou.GFramework.Cqrs and GeWuYou.GFramework.Cqrs.Abstractions even though the module overview recommends CQRS as a first-class module.
• Confirmed docs/zh-CN/source-generators/index.md lists the split CQRS generator package but does not provide a dedicated CQRS handler-registry section with package wiring, minimal usage, or compatibility notes.
• Confirmed GFramework.Cqrs.Tests/Cqrs/CqrsHandlerRegistrarTests.cs has a cross-container metadata-cache test that only asserts reflection/attribute call counts and does not prove the second container still receives registrations.
• Confirmed GFramework.Cqrs/Internal/CqrsDispatcher.cs and GFramework.Cqrs/Internal/CqrsHandlerRegistrar.cs currently use process-wide ConcurrentDictionary<Type, ...> / ConcurrentDictionary<Assembly, ...> caches that strongly retain collectible types and assemblies.
• Reviewed docs/zh-CN/getting-started/installation.md as a related setup entry page; it also omits the CQRS runtime packages from the installation snippets.

Current Recovery Point

• CQRS-CACHE-DOCS-HARDENING-RP-001

Immediate Next Step

1. Update the tracking document and then patch the docs, runtime caches, and tests in one pass.

Stage: Implementation

• Updated README.md quick-install guidance to include:
  • GeWuYou.GFramework.Cqrs
  • GeWuYou.GFramework.Cqrs.Abstractions
• Updated docs/zh-CN/getting-started/installation.md to add CQRS runtime package rows and installation snippets, and corrected the installation verification sample to the current GFramework.Core.Architectures / OnInitialize() / OnInit() API shape.
• Updated docs/zh-CN/core/cqrs.md to add explicit CQRS package wiring and document the current namespace split between message base types (GFramework.Cqrs.*) and handler base types (GFramework.Cqrs.Cqrs.*).
• Updated docs/zh-CN/source-generators/index.md to add a dedicated CQRS Handler Registry 生成器 section covering:
  • required runtime and generator packages
  • a minimal working architecture example
  • compatibility and migration notes for reflection fallback vs generated registries
• Added GFramework.Cqrs/Internal/WeakKeyCache.cs with unload-aware weak-key cache helpers built on ConditionalWeakTable.
• Replaced the CQRS runtime's process-wide strong-reference type/assembly caches with weak-key caches in:
  • GFramework.Cqrs/Internal/CqrsDispatcher.cs
  • GFramework.Cqrs/Internal/CqrsHandlerRegistrar.cs
• Expanded GFramework.Cqrs.Tests/Cqrs/CqrsHandlerRegistrarTests.cs so the cross-container metadata-cache test now proves both containers still resolve the expected handlers after the cache is reused.
• Updated GFramework.Cqrs.Tests/Cqrs/CqrsDispatcherCacheTests.cs to assert cache reuse through observable cached entries instead of assuming ConcurrentDictionary-specific count semantics.
• Evaluated the suggestion to change handler doc examples from using GFramework.Cqrs.Cqrs.Command; to using GFramework.Cqrs.Command;. The repository's actual handler base types still live under GFramework.Cqrs.Cqrs.*, so the implementation kept the real API and clarified the namespace split in the docs instead of documenting a non-existent namespace.

Stage: Validation

• Ran:
  • dotnet test GFramework.Cqrs.Tests/GFramework.Cqrs.Tests.csproj -c Release
• Result:
  • passed, 62 tests passed
• The first validation run surfaced one nullable warning in GFramework.Cqrs/Internal/WeakKeyCache.cs because the nested weak cache lookup did not prove the secondary cache was non-null to the compiler.

Stage: Validation Follow-up

• Fixed WeakTypePairCache<TValue>.TryGetValue(...) to guard the nested weak cache reference explicitly.
• Re-ran:
  • dotnet test GFramework.Cqrs.Tests/GFramework.Cqrs.Tests.csproj -c Release --no-restore
• Result:
  • passed, 62 tests passed

Immediate Next Step

1. Stop at CQRS-CACHE-DOCS-HARDENING-RP-001 unless broader solution-level validation is requested.

Stage: Minor Follow-up

• Updated docs/zh-CN/core/cqrs.md again so the standalone handler snippet now imports both:
  • GFramework.Cqrs.Command
  • GFramework.Cqrs.Cqrs.Command
• Added XML documentation to the private nested binding types in GFramework.Cqrs/Internal/CqrsDispatcher.cs so the intent of the cached service-type/delegate bundles is explicit to future maintainers.
• Restored the explicit using System.Runtime.CompilerServices; directive at the top of GFramework.Cqrs/Internal/WeakKeyCache.cs so ConditionalWeakTable<,> does not rely on ambient imports.
• Added a stateful WeakKeyCache<TKey, TValue>.GetOrAdd<TState>(...) overload and updated WeakTypePairCache<TValue>.GetOrAdd(...) to use it, removing the captured lambda allocation from the secondary-key lookup path.
• Updated both WeakKeyCache<TKey, TValue>.GetOrAdd(...) XML comments to state the full contract: valueFactory itself must be non-null, and it must not produce a null cache value.