GFramework/ai-plan/public/archive/cqrs-cache-docs-hardening/todos/cqrs-cache-docs-hardening-tracking.md

CQRS Cache And Docs Hardening Tracking

Goal

Address the current CQRS follow-up issues across runtime caches, tests, and user-facing setup/integration documentation so the repository state matches the published onboarding path and the runtime remains safe for collectible assemblies.

Current Recovery Point

• Recovery point: CQRS-CACHE-DOCS-HARDENING-RP-001
• Current phase: Phase 2
• Active focus:
  • validation completed for the targeted CQRS test project
  • the repository can resume from documentation follow-up or broader solution validation if needed

Planned Work

• Create the matching execution trace under ai-plan/public/archive/cqrs-cache-docs-hardening/traces/.
• Update README.md quick-install guidance to include CQRS runtime packages.
• Update the related Chinese setup/integration docs with CQRS runtime + source-generator wiring and a minimal working CQRS generator example.
• Replace static ConcurrentDictionary<Assembly, ...> / ConcurrentDictionary<Type, ...> CQRS caches with weak-key caches that do not permanently root collectible assemblies or handler/message types.
• Document the weak-cache thread-safety assumptions and recomputation behavior in code comments/XML docs.
• Expand CQRS tests to assert that cached metadata still results in successful registration in every container.
• Adapt dispatcher cache tests to the new unload-aware cache structure.
• Run targeted CQRS test validation and capture the results here and in the trace.

Validation

Executed:

dotnet test GFramework.Cqrs.Tests/GFramework.Cqrs.Tests.csproj -c Release
dotnet test GFramework.Cqrs.Tests/GFramework.Cqrs.Tests.csproj -c Release --no-restore

Results:

• dotnet test ... -c Release: passed, 62 tests passed.
• dotnet test ... -c Release --no-restore: passed, 62 tests passed.
• The first run exposed one nullable warning in GFramework.Cqrs/Internal/WeakKeyCache.cs; the follow-up fixed the WeakTypePairCache.TryGetValue(...) null-flow and reran the full CQRS test project cleanly.
• The CQRS doc update intentionally did not rename handler examples from GFramework.Cqrs.Cqrs.* to GFramework.Cqrs.*, because the current public handler base types still live under the double-Cqrs namespace. Instead, the docs now explain the split between message namespaces and handler namespaces explicitly.
• A later follow-up added the missing using GFramework.Cqrs.Command; to the handler snippet so that the block can be copied independently, documented the private dispatch-binding types in CqrsDispatcher, restored the explicit System.Runtime.CompilerServices import in WeakKeyCache.cs, and removed the WeakTypePairCache.GetOrAdd(...) closure allocation by routing the secondary-key factory through a stateful overload.
• A final documentation cleanup aligned the WeakKeyCache<TKey, TValue>.GetOrAdd(...) XML comments with the runtime contract by stating that valueFactory must not return null.

Known Risks

• ConditionalWeakTable-based caches trade deterministic retention for unload safety, so the implementation must make the recomputation semantics explicit and keep hot-path lookups thread-safe.
• The source-generator docs already cover multiple generator families; adding CQRS guidance must stay aligned with the actual runtime APIs and package split.
• The existing CQRS docs mix conceptual snippets and minimal examples; changes should improve correctness without silently inventing APIs that the current packages do not expose.

Recommended Resume Step

1. If broader regression confidence is needed, run solution-level CQRS/Core validation next.
2. If the public CQRS handler namespaces are flattened in a future refactor, update the docs again in the same change.