Add documentation on the Windows Runtime event infrastructure

[Sergio0694]

Summary

Add a maintainer-focused deep-dive document (docs/event-infrastructure.md) covering how CsWinRT's Windows Runtime event infrastructure works in WinRT.Runtime2: event sources, event states, the event source cache, registration tokens, the RCW and CCW event flows, lifetime/GC semantics, and the behavior of static events across COM context switches.

Motivation

The event infrastructure is one of the more intricate parts of WinRT.Runtime2 — it spans EventSource<T> / EventSourceState<T> / EventSourceCache / EventRegistrationTokenTable<T>, COM reference counting, reference-tracker integration, dynamic interface casting, and context-aware object references. That makes it easy to get subtly wrong when modifying or debugging, and there was no single reference explaining how the pieces fit together. This document provides that reference, with each claim verified against the current code.

It supersedes #2320: the content was re-verified end-to-end against the implementation, and several inaccuracies in the original draft were corrected (see Changes).

Changes

• docs/event-infrastructure.md (new): a deep-dive reference for the WinRT.Runtime2 event infrastructure. It covers the core types (EventRegistrationToken, EventSource<T> and its per-delegate-shape subclasses, EventSourceState<T>, EventSourceCache, and EventRegistrationTokenTable<T> including its token bit layout), the RCW (managed → native) subscribe/unsubscribe flows with object diagrams, the CCW (native → managed) flow, lifetime/GC semantics (what keeps what alive, the EventInvoke delegate / CCW relationship, reference-tracker integration, cleanup on GC, and a thread-safety summary), and an in-depth analysis of the static-event lifetime issue across COM context switches.

Key points the document clarifies

• Instance-event sources are stored either in a per-instance _eventSource_<name> field on a concrete projected runtime class, or in a ConditionalWeakTable<WindowsRuntimeObject, EventSource<T>> keyed on the object when the interface is reached through a dynamic interface cast ([DynamicInterfaceCastableImplementation] proxies — the mapped interfaces, the WindowsRuntimeInspectable fallback, and generated IDIC proxies). Either way the event source's lifetime is bounded by the WindowsRuntimeObject.
• Static events have no such bound: they key a ConditionalWeakTable on the activation-factory object reference, which is re-fetched on context switches — an unstable key that can orphan an active subscription. The document analyzes the root cause and a possible fix, noting that context-aware object references already marshal native add/remove calls to the current context (best-effort), so the real trade-off of a stable key is lifetime, not call correctness.

Corrections relative to the original draft (#2320)

• Instance events are stored in a per-instance field or a per-object ConditionalWeakTable (dynamic interface cast), rather than a ConditionalWeakTable<WindowsRuntimeObject, EventSource> being the single mechanism.
• The lazy static factory object reference is produced by WindowsRuntimeObjectReference.GetActivationFactory(...) (corrected from WindowsRuntimeActivationFactory, which only exposes GetActivationFactoryUnsafe).
• The cross-context analysis was corrected to remove an internal contradiction: context-aware object references marshal native calls to the current context, so a stable cache key's real cost is lifetime (a leak), not call correctness.
• The GC-cleanup description now matches the current EventSourceState<T>.OnDispose(), which captures the saved native pointer before clearing the field so the EventSourceCache entry is actually removed (addresses the Add docs on Windows Runtime events infrastructure #2320 review comments).