com.wallstop-studios.dxmessaging 3.0.1 → 3.2.0

package/Runtime/Core/MessageRegistrationToken.cs

@@ -2,6 +2,7 @@ namespace DxMessaging.Core
 {
     using System;
     using System.Collections.Generic;
+    using System.Runtime.ExceptionServices;
     using DataStructure;
     using Diagnostics;
     using MessageBus;
@@ -57,17 +58,81 @@ namespace DxMessaging.Core
 
         private readonly MessageHandler _messageHandler;
 
-        private readonly Dictionary<MessageRegistrationHandle, Action> _registrations = new();
-        private readonly Dictionary<MessageRegistrationHandle, Action> _deregistrations = new();
-        private readonly List<Action> _actionQueue = new();
+        // Maps each staged registration handle to the unified per-handle Registration
+        // object the public Register* methods built. Calling Registration.Register()
+        // (re)registers the handler on the bus and returns the matching
+        // HandlerDeregistration. The Registration object IS the collapsed staging
+        // state: it replaces (a) the per-registration staging Func display class, (b)
+        // the staging Func delegate itself, and (c) the nested AugmentedHandler
+        // local-function delegate -- the captured target/source, user handler,
+        // priority, and kind are now plain fields, and the diagnostics-augmented
+        // invoker is an instance method bound to the object (the FastHandler<T> handed
+        // to MessageHandler is (FastHandler<T>)registration.AugmentedHandlerScalar).
+        // Net ~ -2 managed allocations per registration. The central replay loop pairs
+        // the Registration with its handle and performs the AddDeregistration. The
+        // re-entrancy snapshot semantics are unchanged: the replay queue captures the
+        // Registration reference (exactly as it previously captured the staging Func),
+        // so a registration removed mid-replay is still replayed if it was already
+        // snapshotted.
+        private readonly Dictionary<MessageRegistrationHandle, Registration> _registrations = new();
+
+        // Staged-registration handles in registration order. Dictionary
+        // enumeration order is NOT stable across Remove/Add churn, so Enable()
+        // (and RetargetMessageBus) replay staged registrations by walking this
+        // list instead of _registrations.Values; otherwise a Disable()/Enable()
+        // cycle after churn would silently permute the documented
+        // "same priority uses registration order" dispatch contract.
+        // Invariant: contains exactly the keys of _registrations, in the order
+        // InternalRegister staged them (handle ids are monotonically
+        // increasing, so this list is also sorted by handle id).
+        private readonly List<MessageRegistrationHandle> _registrationOrder = new();
+
+        // Maps a handle to its live de-registration(s). The common case is EXACTLY ONE
+        // de-registration per handle, so the single Action is stored INLINE as the dictionary
+        // value (presence == pending, removal == done, keep-on-throw == retryable) -- no
+        // per-registration PendingDeregistration object. A PendingDeregistration is allocated and
+        // substituted ONLY when a second de-registration accumulates on the same handle (the rare
+        // retarget-recovery replay; see AddDeregistration). The value is therefore either an
+        // Action (1 de-registration) or a PendingDeregistration (2+).
+        private readonly Dictionary<MessageRegistrationHandle, object> _deregistrations = new();
+
+        // Snapshot of (handle, Registration object) pairs to replay on Enable() /
+        // RetargetMessageBus. Snapshotting before invoking lets replay tolerate
+        // re-entrant registration mutation (a handler that registers or removes
+        // handlers while it runs). The pair carries the handle so the central replay
+        // loop can call Registration.Register() and AddDeregistration without a
+        // per-registration wrapper closure.
+        private readonly List<StagedRegistration> _registrationReplayQueue = new();
+        private readonly List<MessageRegistrationHandle> _handleQueue = new();
         internal readonly Dictionary<
             MessageRegistrationHandle,
             MessageRegistrationMetadata
         > _metadata = new();
-        internal readonly Dictionary<MessageRegistrationHandle, int> _callCounts = new();
-        internal readonly CyclicBuffer<MessageEmissionData> _emissionBuffer = new(
-            IMessageBus.GlobalMessageBufferSize
-        );
+
+        // Diagnostics-only collections, allocated lazily on first use. A token whose
+        // owner never enables diagnostics (the default -- GlobalDiagnosticsTargets is
+        // Off -- and the common player case) never materializes them, saving the
+        // dictionary, the cyclic buffer, and the buffer's two backing lists per token.
+        // These are exposed as properties under their original field names so the
+        // inspector overlay and the diagnostics tests (which read token._callCounts /
+        // token._emissionBuffer) compile and behave unchanged; the getter caches into
+        // the backing field, so repeated reads return the same instance and an editor
+        // read simply materializes an empty collection. The only production writers are
+        // the dispatch-time AugmentedHandler bodies, all guarded by _diagnosticMode, so
+        // production-with-diagnostics-off never triggers the allocation. Teardown
+        // (ClearDiagnosticState / RemoveRegistrationState /
+        // PruneRegistrationStateToFailedDeregistrations) clears through the backing
+        // fields to avoid materializing a collection just to empty it.
+        private Dictionary<MessageRegistrationHandle, int> _callCountsBacking;
+        private CyclicBuffer<MessageEmissionData> _emissionBufferBacking;
+
+        internal Dictionary<MessageRegistrationHandle, int> _callCounts =>
+            _callCountsBacking ??= new Dictionary<MessageRegistrationHandle, int>();
+
+        internal CyclicBuffer<MessageEmissionData> _emissionBuffer =>
+            _emissionBufferBacking ??= new CyclicBuffer<MessageEmissionData>(
+                IMessageBus.GlobalMessageBufferSize
+            );
 
         private IMessageBus _messageBus;
         private bool _enabled;
@@ -93,33 +158,19 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterTargetedMessageHandler(
-                        target,
-                        targetedHandler,
-                        AugmentedHandler,
-                        priority: priority,
-                        messageBus: _messageBus
-                    );
-
-                    void AugmentedHandler(T message)
-                    {
-                        targetedHandler(message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, target));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        target,
-                        typeof(T),
-                        MessageRegistrationType.Targeted,
-                        priority
-                    )
+                new TargetedRegistration<T>(
+                    this,
+                    RegistrationKind.TargetedHandlerAction,
+                    target,
+                    targetedHandler,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    target,
+                    typeof(T),
+                    MessageRegistrationType.Targeted,
+                    priority
+                )
             );
         }
 
@@ -136,33 +187,19 @@ namespace DxMessaging.Core
             }
 
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterTargetedMessageHandler(
-                        target,
-                        targetedHandler,
-                        AugmentedHandler,
-                        priority: priority,
-                        messageBus: _messageBus
-                    );
-
-                    void AugmentedHandler(ref T message)
-                    {
-                        targetedHandler(ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, target));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        target,
-                        typeof(T),
-                        MessageRegistrationType.Targeted,
-                        priority
-                    )
+                new TargetedRegistration<T>(
+                    this,
+                    RegistrationKind.TargetedHandlerFast,
+                    target,
+                    targetedHandler,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    target,
+                    typeof(T),
+                    MessageRegistrationType.Targeted,
+                    priority
+                )
             );
         }
 
@@ -284,33 +321,19 @@ namespace DxMessaging.Core
             where T : ITargetedMessage
         {
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterTargetedPostProcessor(
-                        target,
-                        targetedPostProcessor,
-                        AugmentedHandler,
-                        priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(ref T message)
-                    {
-                        targetedPostProcessor(ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, target));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        target,
-                        typeof(T),
-                        MessageRegistrationType.TargetedPostProcessor,
-                        priority
-                    )
+                new TargetedRegistration<T>(
+                    this,
+                    RegistrationKind.TargetedPostProcessorFast,
+                    target,
+                    targetedPostProcessor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    target,
+                    typeof(T),
+                    MessageRegistrationType.TargetedPostProcessor,
+                    priority
+                )
             );
         }
 
@@ -330,33 +353,19 @@ namespace DxMessaging.Core
             where T : ITargetedMessage
         {
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterTargetedPostProcessor(
-                        target,
-                        targetedPostProcessor,
-                        AugmentedHandler,
-                        priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(ref T message)
-                    {
-                        targetedPostProcessor(ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, target));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        target,
-                        typeof(T),
-                        MessageRegistrationType.TargetedPostProcessor,
-                        priority
-                    )
+                new TargetedRegistration<T>(
+                    this,
+                    RegistrationKind.TargetedPostProcessorFast,
+                    target,
+                    targetedPostProcessor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    target,
+                    typeof(T),
+                    MessageRegistrationType.TargetedPostProcessor,
+                    priority
+                )
             );
         }
 #endif
@@ -419,33 +428,19 @@ namespace DxMessaging.Core
             where T : ITargetedMessage
         {
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterTargetedPostProcessor(
-                        target,
-                        targetedPostProcessor,
-                        AugmentedHandler,
-                        priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(ref T message)
-                    {
-                        targetedPostProcessor(ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, target));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        target,
-                        typeof(T),
-                        MessageRegistrationType.TargetedPostProcessor,
-                        priority
-                    )
+                new TargetedRegistration<T>(
+                    this,
+                    RegistrationKind.TargetedPostProcessorFast,
+                    target,
+                    targetedPostProcessor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    target,
+                    typeof(T),
+                    MessageRegistrationType.TargetedPostProcessor,
+                    priority
+                )
             );
         }
 
@@ -465,33 +460,19 @@ namespace DxMessaging.Core
             where T : ITargetedMessage
         {
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterTargetedPostProcessor(
-                        target,
-                        targetedPostProcessor,
-                        AugmentedHandler,
-                        priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(T message)
-                    {
-                        targetedPostProcessor(message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, target));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        target,
-                        typeof(T),
-                        MessageRegistrationType.TargetedPostProcessor,
-                        priority
-                    )
+                new TargetedRegistration<T>(
+                    this,
+                    RegistrationKind.TargetedPostProcessorAction,
+                    target,
+                    targetedPostProcessor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    target,
+                    typeof(T),
+                    MessageRegistrationType.TargetedPostProcessor,
+                    priority
+                )
             );
         }
 
@@ -516,32 +497,19 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterTargetedWithoutTargeting(
-                        messageHandler,
-                        AugmentedHandler,
-                        priority: priority,
-                        messageBus: _messageBus
-                    );
-
-                    void AugmentedHandler(InstanceId target, T message)
-                    {
-                        messageHandler(target, message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, target));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.TargetedWithoutTargeting,
-                        priority
-                    )
+                new TargetedRegistration<T>(
+                    this,
+                    RegistrationKind.TargetedWithoutTargetingAction,
+                    default,
+                    messageHandler,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.TargetedWithoutTargeting,
+                    priority
+                )
             );
         }
 
@@ -566,32 +534,19 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterTargetedWithoutTargeting(
-                        messageHandler,
-                        AugmentedHandler,
-                        priority: priority,
-                        messageBus: _messageBus
-                    );
-
-                    void AugmentedHandler(ref InstanceId target, ref T message)
-                    {
-                        messageHandler(ref target, ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, target));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.TargetedWithoutTargeting,
-                        priority
-                    )
+                new TargetedRegistration<T>(
+                    this,
+                    RegistrationKind.TargetedWithoutTargetingFast,
+                    default,
+                    messageHandler,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.TargetedWithoutTargeting,
+                    priority
+                )
             );
         }
 
@@ -616,32 +571,19 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterTargetedWithoutTargetingPostProcessor(
-                        postProcessor,
-                        AugmentedHandler,
-                        priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(InstanceId target, T message)
-                    {
-                        postProcessor(target, message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, target));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.TargetedWithoutTargetingPostProcessor,
-                        priority
-                    )
+                new TargetedRegistration<T>(
+                    this,
+                    RegistrationKind.TargetedWithoutTargetingPostProcessorAction,
+                    default,
+                    postProcessor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.TargetedWithoutTargetingPostProcessor,
+                    priority
+                )
             );
         }
 
@@ -666,32 +608,19 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterTargetedWithoutTargetingPostProcessor(
-                        postProcessor,
-                        AugmentedHandler,
-                        priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(ref InstanceId target, ref T message)
-                    {
-                        postProcessor(ref target, ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, target));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.TargetedWithoutTargetingPostProcessor,
-                        priority
-                    )
+                new TargetedRegistration<T>(
+                    this,
+                    RegistrationKind.TargetedWithoutTargetingPostProcessorFast,
+                    default,
+                    postProcessor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.TargetedWithoutTargetingPostProcessor,
+                    priority
+                )
             );
         }
 
@@ -723,32 +652,18 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterUntargetedMessageHandler(
-                        untargetedHandler,
-                        AugmentedHandler,
-                        priority: priority,
-                        messageBus: _messageBus
-                    );
-
-                    void AugmentedHandler(T message)
-                    {
-                        untargetedHandler(message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.Untargeted,
-                        priority
-                    )
+                new UntargetedRegistration<T>(
+                    this,
+                    RegistrationKind.UntargetedHandlerAction,
+                    untargetedHandler,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.Untargeted,
+                    priority
+                )
             );
         }
 
@@ -779,32 +694,18 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterUntargetedMessageHandler(
-                        untargetedHandler,
-                        AugmentedHandler,
-                        priority: priority,
-                        messageBus: _messageBus
-                    );
-
-                    void AugmentedHandler(ref T message)
-                    {
-                        untargetedHandler(ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.Untargeted,
-                        priority
-                    )
+                new UntargetedRegistration<T>(
+                    this,
+                    RegistrationKind.UntargetedHandlerFast,
+                    untargetedHandler,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.Untargeted,
+                    priority
+                )
             );
         }
 
@@ -826,32 +727,18 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterUntargetedPostProcessor(
-                        untargetedPostProcessor,
-                        AugmentedHandler,
-                        priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(ref T message)
-                    {
-                        untargetedPostProcessor(ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.UntargetedPostProcessor,
-                        priority
-                    )
+                new UntargetedRegistration<T>(
+                    this,
+                    RegistrationKind.UntargetedPostProcessorFast,
+                    untargetedPostProcessor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.UntargetedPostProcessor,
+                    priority
+                )
             );
         }
 
@@ -867,33 +754,19 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterSourcedBroadcastMessageHandler(
-                        source,
-                        broadcastHandler,
-                        AugmentedHandler,
-                        priority: priority,
-                        messageBus: _messageBus
-                    );
-
-                    void AugmentedHandler(T message)
-                    {
-                        broadcastHandler(message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, source));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        source,
-                        typeof(T),
-                        MessageRegistrationType.Broadcast,
-                        priority
-                    )
+                new BroadcastRegistration<T>(
+                    this,
+                    RegistrationKind.BroadcastHandlerAction,
+                    source,
+                    broadcastHandler,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    source,
+                    typeof(T),
+                    MessageRegistrationType.Broadcast,
+                    priority
+                )
             );
         }
 
@@ -909,33 +782,19 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterSourcedBroadcastMessageHandler(
-                        source,
-                        broadcastHandler,
-                        AugmentedHandler,
-                        priority: priority,
-                        messageBus: _messageBus
-                    );
-
-                    void AugmentedHandler(ref T message)
-                    {
-                        broadcastHandler(ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, source));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        source,
-                        typeof(T),
-                        MessageRegistrationType.Broadcast,
-                        priority
-                    )
+                new BroadcastRegistration<T>(
+                    this,
+                    RegistrationKind.BroadcastHandlerFast,
+                    source,
+                    broadcastHandler,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    source,
+                    typeof(T),
+                    MessageRegistrationType.Broadcast,
+                    priority
+                )
             );
         }
 
@@ -952,33 +811,19 @@ namespace DxMessaging.Core
             }
 
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterSourcedBroadcastPostProcessor(
-                        source,
-                        broadcastPostProcessor,
-                        AugmentedHandler,
-                        priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(T message)
-                    {
-                        broadcastPostProcessor(message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, source));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        source,
-                        typeof(T),
-                        MessageRegistrationType.BroadcastPostProcessor,
-                        priority
-                    )
+                new BroadcastRegistration<T>(
+                    this,
+                    RegistrationKind.BroadcastPostProcessorAction,
+                    source,
+                    broadcastPostProcessor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    source,
+                    typeof(T),
+                    MessageRegistrationType.BroadcastPostProcessor,
+                    priority
+                )
             );
         }
 
@@ -994,33 +839,19 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterSourcedBroadcastPostProcessor(
-                        source,
-                        broadcastPostProcessor,
-                        AugmentedHandler,
-                        priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(ref T message)
-                    {
-                        broadcastPostProcessor(ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, source));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        source,
-                        typeof(T),
-                        MessageRegistrationType.BroadcastPostProcessor,
-                        priority
-                    )
+                new BroadcastRegistration<T>(
+                    this,
+                    RegistrationKind.BroadcastPostProcessorFast,
+                    source,
+                    broadcastPostProcessor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    source,
+                    typeof(T),
+                    MessageRegistrationType.BroadcastPostProcessor,
+                    priority
+                )
             );
         }
 
@@ -1165,33 +996,19 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterSourcedBroadcastPostProcessor(
-                        source,
-                        broadcastPostProcessor,
-                        AugmentedHandler,
-                        priority: priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(T message)
-                    {
-                        broadcastPostProcessor(message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, source));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        source,
-                        typeof(T),
-                        MessageRegistrationType.BroadcastPostProcessor,
-                        priority
-                    )
+                new BroadcastRegistration<T>(
+                    this,
+                    RegistrationKind.BroadcastPostProcessorAction,
+                    source,
+                    broadcastPostProcessor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    source,
+                    typeof(T),
+                    MessageRegistrationType.BroadcastPostProcessor,
+                    priority
+                )
             );
         }
 
@@ -1215,33 +1032,19 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterSourcedBroadcastPostProcessor(
-                        source,
-                        broadcastPostProcessor,
-                        AugmentedHandler,
-                        priority: priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(ref T message)
-                    {
-                        broadcastPostProcessor(ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, source));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        source,
-                        typeof(T),
-                        MessageRegistrationType.BroadcastPostProcessor,
-                        priority
-                    )
+                new BroadcastRegistration<T>(
+                    this,
+                    RegistrationKind.BroadcastPostProcessorFast,
+                    source,
+                    broadcastPostProcessor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    source,
+                    typeof(T),
+                    MessageRegistrationType.BroadcastPostProcessor,
+                    priority
+                )
             );
         }
 #endif
@@ -1357,32 +1160,19 @@ namespace DxMessaging.Core
             }
 
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterSourcedBroadcastWithoutSource(
-                        broadcastHandler,
-                        AugmentedHandler,
-                        priority: priority,
-                        messageBus: _messageBus
-                    );
-
-                    void AugmentedHandler(InstanceId source, T message)
-                    {
-                        broadcastHandler(source, message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, source));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.BroadcastWithoutSource,
-                        priority
-                    )
+                new BroadcastRegistration<T>(
+                    this,
+                    RegistrationKind.BroadcastWithoutSourceAction,
+                    default,
+                    broadcastHandler,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.BroadcastWithoutSource,
+                    priority
+                )
             );
         }
 
@@ -1408,32 +1198,19 @@ namespace DxMessaging.Core
             }
 
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterSourcedBroadcastWithoutSource(
-                        broadcastHandler,
-                        AugmentedHandler,
-                        priority: priority,
-                        messageBus: _messageBus
-                    );
-
-                    void AugmentedHandler(ref InstanceId source, ref T message)
-                    {
-                        broadcastHandler(ref source, ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, source));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.BroadcastWithoutSource,
-                        priority
-                    )
+                new BroadcastRegistration<T>(
+                    this,
+                    RegistrationKind.BroadcastWithoutSourceFast,
+                    default,
+                    broadcastHandler,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.BroadcastWithoutSource,
+                    priority
+                )
             );
         }
 
@@ -1464,32 +1241,19 @@ namespace DxMessaging.Core
             }
 
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterSourcedBroadcastWithoutSourcePostProcessor(
-                        broadcastHandler,
-                        AugmentedHandler,
-                        priority: priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(InstanceId source, T message)
-                    {
-                        broadcastHandler(source, message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, source));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.BroadcastWithoutSourcePostProcessor,
-                        priority
-                    )
+                new BroadcastRegistration<T>(
+                    this,
+                    RegistrationKind.BroadcastWithoutSourcePostProcessorAction,
+                    default,
+                    broadcastHandler,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.BroadcastWithoutSourcePostProcessor,
+                    priority
+                )
             );
         }
 
@@ -1515,32 +1279,19 @@ namespace DxMessaging.Core
             }
 
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterSourcedBroadcastWithoutSourcePostProcessor(
-                        broadcastHandler,
-                        AugmentedHandler,
-                        priority: priority,
-                        _messageBus
-                    );
-
-                    void AugmentedHandler(ref InstanceId source, ref T message)
-                    {
-                        broadcastHandler(ref source, ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, source));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.BroadcastWithoutSourcePostProcessor,
-                        priority
-                    )
+                new BroadcastRegistration<T>(
+                    this,
+                    RegistrationKind.BroadcastWithoutSourcePostProcessorFast,
+                    default,
+                    broadcastHandler,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.BroadcastWithoutSourcePostProcessor,
+                    priority
+                )
             );
         }
 
@@ -1565,55 +1316,18 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterGlobalAcceptAll(
-                        acceptAllUntargeted,
-                        AugmentedUntargeted,
-                        acceptAllTargeted,
-                        AugmentedTargeted,
-                        acceptAllBroadcast,
-                        AugmentedBroadcast,
-                        _messageBus
-                    );
-
-                    void AugmentedUntargeted(IUntargetedMessage message)
-                    {
-                        acceptAllUntargeted(message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message));
-                        }
-                    }
-
-                    void AugmentedTargeted(InstanceId target, ITargetedMessage message)
-                    {
-                        acceptAllTargeted(target, message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, target));
-                        }
-                    }
-
-                    void AugmentedBroadcast(InstanceId source, IBroadcastMessage message)
-                    {
-                        acceptAllBroadcast(source, message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, source));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(IMessage),
-                        MessageRegistrationType.GlobalAcceptAll,
-                        0
-                    )
+                new GlobalAcceptAllRegistration(
+                    this,
+                    acceptAllUntargeted,
+                    acceptAllTargeted,
+                    acceptAllBroadcast
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(IMessage),
+                    MessageRegistrationType.GlobalAcceptAll,
+                    0
+                )
             );
         }
 
@@ -1647,55 +1361,18 @@ namespace DxMessaging.Core
                 return MessageRegistrationHandle.CreateMessageRegistrationHandle();
             }
             return InternalRegister(
-                handle =>
-                {
-                    return _messageHandler.RegisterGlobalAcceptAll(
-                        acceptAllUntargeted,
-                        AugmentedUntargeted,
-                        acceptAllTargeted,
-                        AugmentedTargeted,
-                        acceptAllBroadcast,
-                        AugmentedBroadcast,
-                        _messageBus
-                    );
-
-                    void AugmentedUntargeted(ref IUntargetedMessage message)
-                    {
-                        acceptAllUntargeted(ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message));
-                        }
-                    }
-
-                    void AugmentedTargeted(ref InstanceId target, ref ITargetedMessage message)
-                    {
-                        acceptAllTargeted(ref target, ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, target));
-                        }
-                    }
-
-                    void AugmentedBroadcast(ref InstanceId source, ref IBroadcastMessage message)
-                    {
-                        acceptAllBroadcast(ref source, ref message);
-                        if (_diagnosticMode)
-                        {
-                            _callCounts[handle] = _callCounts.GetValueOrDefault(handle) + 1;
-                            _emissionBuffer.Add(new MessageEmissionData(message, source));
-                        }
-                    }
-                },
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(IMessage),
-                        MessageRegistrationType.GlobalAcceptAll,
-                        0
-                    )
+                new GlobalAcceptAllRegistration(
+                    this,
+                    acceptAllUntargeted,
+                    acceptAllTargeted,
+                    acceptAllBroadcast
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(IMessage),
+                    MessageRegistrationType.GlobalAcceptAll,
+                    0
+                )
             );
         }
 
@@ -1718,14 +1395,18 @@ namespace DxMessaging.Core
             }
 
             return InternalRegister(
-                _ => _messageHandler.RegisterUntargetedInterceptor(interceptor, priority),
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.UntargetedInterceptor,
-                        priority
-                    )
+                new UntargetedRegistration<T>(
+                    this,
+                    RegistrationKind.UntargetedInterceptor,
+                    interceptor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.UntargetedInterceptor,
+                    priority
+                )
             );
         }
 
@@ -1748,14 +1429,19 @@ namespace DxMessaging.Core
             }
 
             return InternalRegister(
-                _ => _messageHandler.RegisterBroadcastInterceptor(interceptor, priority),
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.BroadcastInterceptor,
-                        priority
-                    )
+                new BroadcastRegistration<T>(
+                    this,
+                    RegistrationKind.BroadcastInterceptor,
+                    default,
+                    interceptor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.BroadcastInterceptor,
+                    priority
+                )
             );
         }
 
@@ -1778,48 +1464,61 @@ namespace DxMessaging.Core
             }
 
             return InternalRegister(
-                _ => _messageHandler.RegisterTargetedInterceptor(interceptor, priority),
-                () =>
-                    new MessageRegistrationMetadata(
-                        null,
-                        typeof(T),
-                        MessageRegistrationType.TargetedInterceptor,
-                        priority
-                    )
+                new TargetedRegistration<T>(
+                    this,
+                    RegistrationKind.TargetedInterceptor,
+                    default,
+                    interceptor,
+                    priority
+                ),
+                new MessageRegistrationMetadata(
+                    null,
+                    typeof(T),
+                    MessageRegistrationType.TargetedInterceptor,
+                    priority
+                )
             );
         }
 
         /// <summary>
         /// Handles the actual [de]registration wrapping and (potential) lazy execution.
         /// </summary>
-        /// <param name="registerAndGetDeregistration">Proxied registration function that returns a de-registration function.</param>
-        /// <param name="metadataProducer">Opaque metadata producer function.</param>
+        /// <param name="registration">The unified per-handle registration object the public Register* method built. Calling <see cref="Registration.Register"/> (re)registers the handler on the bus and returns the matching de-registration.</param>
+        /// <param name="metadata">Registration metadata recorded for the diagnostics inspector overlay and the registration-count warning.</param>
         /// <returns>A handle that allows for registration and de-registration.</returns>
         private MessageRegistrationHandle InternalRegister(
-            Func<MessageRegistrationHandle, Action> registerAndGetDeregistration,
-            Func<MessageRegistrationMetadata> metadataProducer
+            Registration registration,
+            MessageRegistrationMetadata metadata
         )
         {
             MessageRegistrationHandle handle =
                 MessageRegistrationHandle.CreateMessageRegistrationHandle();
 
-            _registrations[handle] = Registration;
-            _metadata[handle] = metadataProducer();
-
-            // Generally, registrations should take place before all calls to enable. Just in case, though...
+            registration.Handle = handle;
+            _registrations[handle] = registration;
+            _registrationOrder.Add(handle);
+            // Metadata is passed by value (a readonly struct) instead of through a
+            // Func<MessageRegistrationMetadata> factory: the factory was invoked
+            // immediately and unconditionally here, so it never deferred any work --
+            // it only cost one delegate (plus its display class) allocation per
+            // registration. Constructing the struct at the call site is identical
+            // work without that closure. _metadata stays populated for every
+            // registration because the inspector overlay and the registration-count
+            // warning read it regardless of diagnostics mode.
+            _metadata[handle] = metadata;
+
+            // Generally, registrations should take place before all calls to enable.
+            // Just in case, though, register immediately if already enabled. We do not
+            // register at staging time when disabled (the owner might not be awake), so
+            // the Registration object is retained in _registrations to lazily
+            // (re)register on Enable().
             if (_enabled)
             {
-                Registration();
+                MessageHandler.HandlerDeregistration actualDeregistration = registration.Register();
+                AddDeregistration(handle, actualDeregistration);
             }
 
             return handle;
-
-            // We don't want to actually register at this time (might not be awake/enabled) - so we wrap that shit up, to lazy register when we're enabled.
-            void Registration()
-            {
-                Action actualDeregistration = registerAndGetDeregistration(handle);
-                _deregistrations[handle] = actualDeregistration;
-            }
         }
 
         /// <summary>
@@ -1843,12 +1542,15 @@ namespace DxMessaging.Core
 
             if (_registrations is { Count: > 0 })
             {
-                _actionQueue.Clear();
-                _actionQueue.AddRange(_registrations.Values);
-                foreach (Action action in _actionQueue)
-                {
-                    action();
-                }
+                // Replay staged registrations in original registration order
+                // (via _registrationOrder) rather than in
+                // _registrations.Values enumeration order, which permutes
+                // after Remove/Add churn. This preserves the documented
+                // equal-priority "registration order" dispatch contract across
+                // Disable()/Enable() cycles. Snapshot into _registrationReplayQueue first
+                // so replay tolerates re-entrant registration mutation.
+                QueueRegistrationsInOrder();
+                InvokeRegistrationQueueWithRollback();
             }
 
             _enabled = true;
@@ -1867,28 +1569,21 @@ namespace DxMessaging.Core
         /// </example>
         public void Disable()
         {
-            if (!_enabled)
+            if (!_enabled && _deregistrations.Count == 0)
             {
                 return;
             }
 
-            if (_deregistrations is { Count: > 0 })
+            Exception deregistrationException = InvokeDeregistrationQueue();
+            _enabled = _deregistrations.Count > 0;
+            if (deregistrationException != null)
             {
-                _actionQueue.Clear();
-                _actionQueue.AddRange(_deregistrations.Values);
-                foreach (Action deregistration in _actionQueue)
-                {
-                    deregistration?.Invoke();
-                }
+                ExceptionDispatchInfo.Capture(deregistrationException).Throw();
             }
-
-            // ReSharper disable once ForCanBeConvertedToForeach
-
-            _enabled = false;
         }
 
         /// <summary>
-        /// Disables the token and clears all registrations and de-registrations.
+        /// Disables the token and clears all registrations, de-registrations, and token-local diagnostic state.
         /// </summary>
         /// <example>
         /// <code>
@@ -1899,19 +1594,19 @@ namespace DxMessaging.Core
         /// </example>
         public void UnregisterAll()
         {
-            if (_deregistrations is { Count: > 0 })
+            Exception deregistrationException = InvokeDeregistrationQueue();
+            if (deregistrationException == null)
             {
-                _actionQueue.Clear();
-                _actionQueue.AddRange(_deregistrations.Values);
-                foreach (Action deregistration in _actionQueue)
-                {
-                    deregistration?.Invoke();
-                }
+                _enabled = false;
+                _registrations?.Clear();
+                _registrationOrder?.Clear();
+                ClearDiagnosticState();
+                return;
             }
 
-            _enabled = false;
-            _registrations?.Clear();
-            _deregistrations?.Clear();
+            _enabled = _deregistrations.Count > 0;
+            PruneRegistrationStateToFailedDeregistrations();
+            ExceptionDispatchInfo.Capture(deregistrationException).Throw();
         }
 
         /// <summary>
@@ -1938,52 +1633,1212 @@ namespace DxMessaging.Core
                 return;
             }
 
+            IMessageBus previousMessageBus = _messageBus;
+            List<MessageRegistrationHandle> activeRetargetHandles = rebindActiveRegistrations
+                ? new List<MessageRegistrationHandle>(_deregistrations.Keys)
+                : null;
             if (rebindActiveRegistrations)
             {
-                _actionQueue.Clear();
-                _actionQueue.AddRange(_deregistrations.Values);
-                foreach (Action deregistration in _actionQueue)
+                Exception deregistrationException = InvokeDeregistrationQueue();
+                if (deregistrationException != null)
                 {
-                    deregistration?.Invoke();
+                    RestoreMissingRegistrationsAfterRetargetDeregistrationFailure(
+                        previousMessageBus,
+                        activeRetargetHandles
+                    );
+                    _enabled = _deregistrations.Count > 0;
+                    ExceptionDispatchInfo.Capture(deregistrationException).Throw();
                 }
+
+                _enabled = false;
             }
 
             _messageBus = messageBus;
 
             if (rebindActiveRegistrations && _registrations is { Count: > 0 })
             {
-                _actionQueue.Clear();
-                _actionQueue.AddRange(_registrations.Values);
-                foreach (Action registration in _actionQueue)
+                // Mirror Enable(): rebind in original registration order so the
+                // equal-priority dispatch order survives a bus retarget.
+                QueueRegistrationsInOrder();
+                try
+                {
+                    InvokeRegistrationQueueWithRollback();
+                    _enabled = true;
+                }
+                catch (Exception exception)
                 {
-                    registration?.Invoke();
+                    RestoreRegistrationsAfterRetargetFailure(previousMessageBus);
+                    ExceptionDispatchInfo.Capture(exception).Throw();
+                    throw;
                 }
             }
         }
 
-        /// <summary>
-        /// Removes a single staged registration by handle.
-        /// </summary>
-        /// <param name="handle">Handle returned from a Register* method.</param>
-        /// <example>
-        /// <code>
-        /// var h = token.RegisterUntargeted&lt;SceneLoaded&gt;(OnScene);
-        /// token.RemoveRegistration(h); // de-register just this one
-        /// </code>
-        /// </example>
-        public void RemoveRegistration(MessageRegistrationHandle handle)
+        private void AddDeregistration(
+            MessageRegistrationHandle handle,
+            MessageHandler.HandlerDeregistration deregistration
+        )
         {
-            if (_deregistrations?.Remove(handle, out Action deregistrationAction) == true)
+            // First (and usually only) de-registration: store the object inline in ONE dictionary
+            // operation. TryAdd succeeds on the common first-registration path without the prior
+            // separate TryGetValue-miss + indexer-insert (two probes of the same key); the rare
+            // second-de-registration promotion path below re-reads the existing value.
+            if (_deregistrations.TryAdd(handle, deregistration))
             {
-                deregistrationAction?.Invoke();
+                return;
             }
 
-            // Drop the matching staged registration and metadata so a later
-            // Disable()/Enable() cycle does not silently re-register the
-            // handler we were just asked to remove.
-            _ = _registrations?.Remove(handle);
-            _ = _metadata?.Remove(handle);
-            _ = _callCounts?.Remove(handle);
+            object existing = _deregistrations[handle];
+            if (existing is PendingDeregistration pending)
+            {
+                pending.Add(deregistration);
+                return;
+            }
+
+            // A second de-registration accumulated on this handle: promote the inline object to a
+            // PendingDeregistration holder that preserves the ordering / partial-failure / rollback
+            // semantics for the multi-de-registration (retarget-recovery replay) case.
+            PendingDeregistration promoted = new();
+            promoted.Add((MessageHandler.HandlerDeregistration)existing);
+            promoted.Add(deregistration);
+            _deregistrations[handle] = promoted;
+        }
+
+        // Logical de-registration count for a _deregistrations value (inline object == 1).
+        private static int DeregistrationCount(object value) =>
+            value is PendingDeregistration pending ? pending.Count : 1;
+
+        // Invokes the de-registration tail [startIndex..) for a _deregistrations value. For the
+        // inline object (logical Count 1, index 0): on success it is consumed (shouldRemove = true);
+        // on throw it is KEPT (retryable, shouldRemove = false); a rollback pass (startIndex &gt; 0)
+        // leaves the baseline entry untouched. For a holder it delegates to InvokeFrom, mutating the
+        // holder in place. Mirrors the prior PendingDeregistration-only semantics exactly.
+        private static Exception InvokeDeregistration(
+            object value,
+            int startIndex,
+            out bool shouldRemove
+        )
+        {
+            if (value is PendingDeregistration pending)
+            {
+                Exception holderException = pending.InvokeFrom(startIndex);
+                shouldRemove = pending.Count == 0;
+                return holderException;
+            }
+
+            if (startIndex > 0)
+            {
+                // Rollback baseline pass: the inline head (logical index 0) is below the requested
+                // tail, so leave it untouched.
+                shouldRemove = false;
+                return null;
+            }
+
+            try
+            {
+                ((MessageHandler.HandlerDeregistration)value)?.Deregister();
+                shouldRemove = true;
+                return null;
+            }
+            catch (Exception exception)
+            {
+                // Keep the failed de-registration (retryable), exactly as the holder form does.
+                shouldRemove = false;
+                return exception;
+            }
+        }
+
+        private Dictionary<MessageRegistrationHandle, int> SnapshotDeregistrationCounts()
+        {
+            Dictionary<MessageRegistrationHandle, int> snapshot = new(_deregistrations.Count);
+            foreach (KeyValuePair<MessageRegistrationHandle, object> entry in _deregistrations)
+            {
+                snapshot[entry.Key] = DeregistrationCount(entry.Value);
+            }
+
+            return snapshot;
+        }
+
+        private void RestoreMissingRegistrationsAfterRetargetDeregistrationFailure(
+            IMessageBus previousMessageBus,
+            List<MessageRegistrationHandle> activeRetargetHandles
+        )
+        {
+            _messageBus = previousMessageBus;
+            if (activeRetargetHandles == null || activeRetargetHandles.Count == 0)
+            {
+                return;
+            }
+
+            QueueMissingRegistrationsInOrder(activeRetargetHandles);
+            try
+            {
+                InvokeRegistrationQueueWithRollback();
+            }
+            catch (Exception exception)
+            {
+                if (MessagingDebug.enabled)
+                {
+                    MessagingDebug.Log(
+                        LogLevel.Error,
+                        "Failed to restore registrations after retarget deregistration failure: {0}",
+                        exception
+                    );
+                }
+            }
+        }
+
+        private void RestoreRegistrationsAfterRetargetFailure(IMessageBus previousMessageBus)
+        {
+            _messageBus = previousMessageBus;
+            if (_registrations.Count == 0)
+            {
+                _enabled = false;
+                return;
+            }
+
+            QueueRegistrationsWithoutRetryableDeregistrationsInOrder();
+            try
+            {
+                InvokeRegistrationQueueWithRollback();
+                _enabled = true;
+            }
+            catch (Exception restoreException)
+            {
+                _enabled = _deregistrations.Count > 0;
+                if (MessagingDebug.enabled)
+                {
+                    MessagingDebug.Log(
+                        LogLevel.Error,
+                        "Failed to restore registrations after retarget replay failure: {0}",
+                        restoreException
+                    );
+                }
+            }
+        }
+
+        private void QueueRegistrationsInOrder()
+        {
+            _registrationReplayQueue.Clear();
+            int registrationCount = _registrationOrder.Count;
+            for (int i = 0; i < registrationCount; ++i)
+            {
+                MessageRegistrationHandle handle = _registrationOrder[i];
+                if (_registrations.TryGetValue(handle, out Registration registration))
+                {
+                    _registrationReplayQueue.Add(new StagedRegistration(handle, registration));
+                }
+            }
+        }
+
+        private void QueueMissingRegistrationsInOrder(
+            List<MessageRegistrationHandle> activeRetargetHandles
+        )
+        {
+            _registrationReplayQueue.Clear();
+            int registrationCount = _registrationOrder.Count;
+            for (int i = 0; i < registrationCount; ++i)
+            {
+                MessageRegistrationHandle handle = _registrationOrder[i];
+                if (
+                    !activeRetargetHandles.Contains(handle)
+                    || _deregistrations.ContainsKey(handle)
+                    || !_registrations.TryGetValue(handle, out Registration registration)
+                )
+                {
+                    continue;
+                }
+
+                _registrationReplayQueue.Add(new StagedRegistration(handle, registration));
+            }
+        }
+
+        private void QueueRegistrationsWithoutRetryableDeregistrationsInOrder()
+        {
+            _registrationReplayQueue.Clear();
+            int registrationCount = _registrationOrder.Count;
+            for (int i = 0; i < registrationCount; ++i)
+            {
+                MessageRegistrationHandle handle = _registrationOrder[i];
+                if (
+                    _deregistrations.ContainsKey(handle)
+                    || !_registrations.TryGetValue(handle, out Registration registration)
+                )
+                {
+                    continue;
+                }
+
+                _registrationReplayQueue.Add(new StagedRegistration(handle, registration));
+            }
+        }
+
+        private void InvokeRegistrationReplayQueue()
+        {
+            try
+            {
+                foreach (StagedRegistration staged in _registrationReplayQueue)
+                {
+                    Registration registration = staged.Registration;
+                    if (registration == null)
+                    {
+                        continue;
+                    }
+
+                    MessageHandler.HandlerDeregistration actualDeregistration =
+                        registration.Register();
+                    AddDeregistration(staged.Handle, actualDeregistration);
+                }
+            }
+            finally
+            {
+                _registrationReplayQueue.Clear();
+            }
+        }
+
+        /// <summary>
+        /// A staged registration captured for replay: the handle plus the unified
+        /// per-handle <see cref="Registration"/> object that (re)registers the handler
+        /// and returns its <see cref="MessageHandler.HandlerDeregistration"/>.
+        /// Snapshotting the object reference (rather than a per-registration wrapper
+        /// closure) preserves the original re-entrancy semantics while keeping the
+        /// staging state in a single object per registration.
+        /// </summary>
+        private readonly struct StagedRegistration
+        {
+            public readonly MessageRegistrationHandle Handle;
+            public readonly Registration Registration;
+
+            public StagedRegistration(MessageRegistrationHandle handle, Registration registration)
+            {
+                Handle = handle;
+                Registration = registration;
+            }
+        }
+
+        private Exception InvokeDeregistrationQueue(
+            Dictionary<MessageRegistrationHandle, int> baselineCounts = null
+        )
+        {
+            if (_deregistrations.Count == 0)
+            {
+                return null;
+            }
+
+            bool scopedToAddedDeregistrations = baselineCounts != null;
+            _handleQueue.Clear();
+            _handleQueue.AddRange(_deregistrations.Keys);
+            Exception firstException = null;
+            try
+            {
+                foreach (MessageRegistrationHandle handle in _handleQueue)
+                {
+                    if (!_deregistrations.TryGetValue(handle, out object value))
+                    {
+                        continue;
+                    }
+
+                    int startIndex = 0;
+                    if (scopedToAddedDeregistrations)
+                    {
+                        if (baselineCounts.TryGetValue(handle, out int baselineCount))
+                        {
+                            startIndex = baselineCount;
+                        }
+
+                        if (startIndex >= DeregistrationCount(value))
+                        {
+                            continue;
+                        }
+                    }
+
+                    Exception exception = InvokeDeregistration(
+                        value,
+                        startIndex,
+                        out bool shouldRemove
+                    );
+                    if (exception != null)
+                    {
+                        firstException ??= exception;
+                    }
+
+                    if (shouldRemove)
+                    {
+                        _deregistrations.Remove(handle);
+                    }
+                }
+            }
+            finally
+            {
+                _handleQueue.Clear();
+            }
+
+            return firstException;
+        }
+
+        private void InvokeRegistrationQueueWithRollback()
+        {
+            Dictionary<MessageRegistrationHandle, int> rollbackBaseline =
+                SnapshotDeregistrationCounts();
+            try
+            {
+                InvokeRegistrationReplayQueue();
+            }
+            catch (Exception exception)
+            {
+                RollBackDeregistrationsAfterRegistrationFailure(rollbackBaseline);
+                _enabled = _deregistrations.Count > 0;
+                ExceptionDispatchInfo.Capture(exception).Throw();
+                throw;
+            }
+        }
+
+        private void RollBackDeregistrationsAfterRegistrationFailure(
+            Dictionary<MessageRegistrationHandle, int> rollbackBaseline
+        )
+        {
+            if (_deregistrations.Count == 0)
+            {
+                return;
+            }
+
+            Exception rollbackException = InvokeDeregistrationQueue(rollbackBaseline);
+            if (rollbackException != null && MessagingDebug.enabled)
+            {
+                MessagingDebug.Log(
+                    LogLevel.Error,
+                    "Failed to roll back partial registration after token replay failure: {0}",
+                    rollbackException
+                );
+            }
+        }
+
+        private void ClearDiagnosticState()
+        {
+            _metadata.Clear();
+            // Clear through the backing fields so an inactive (never-materialized)
+            // diagnostics collection is not allocated merely to be emptied.
+            _callCountsBacking?.Clear();
+            _emissionBufferBacking?.Clear();
+        }
+
+        private void PruneRegistrationStateToFailedDeregistrations()
+        {
+            for (int i = _registrationOrder.Count - 1; i >= 0; --i)
+            {
+                MessageRegistrationHandle handle = _registrationOrder[i];
+                if (_deregistrations.ContainsKey(handle))
+                {
+                    continue;
+                }
+
+                RemoveRegistrationState(handle);
+            }
+
+            _emissionBufferBacking?.Clear();
+            if (_registrations.Count == 0)
+            {
+                ClearDiagnosticState();
+            }
+        }
+
+        private bool RemoveRegistrationState(MessageRegistrationHandle handle)
+        {
+            bool removedRegistration = _registrations.Remove(handle);
+            _ = _registrationOrder.Remove(handle);
+            _ = _metadata.Remove(handle);
+            _callCountsBacking?.Remove(handle);
+            if (removedRegistration && _registrations.Count == 0)
+            {
+                ClearDiagnosticState();
+            }
+
+            return removedRegistration;
+        }
+
+        /// <summary>
+        /// Removes a single staged registration by handle.
+        /// </summary>
+        /// <param name="handle">Handle returned from a Register* method.</param>
+        /// <example>
+        /// <code>
+        /// var h = token.RegisterUntargeted&lt;SceneLoaded&gt;(OnScene);
+        /// token.RemoveRegistration(h); // de-register just this one
+        /// </code>
+        /// </example>
+        public void RemoveRegistration(MessageRegistrationHandle handle)
+        {
+            if (_deregistrations.TryGetValue(handle, out object value))
+            {
+                Exception deregistrationException = InvokeDeregistration(
+                    value,
+                    0,
+                    out bool shouldRemove
+                );
+                if (shouldRemove)
+                {
+                    _deregistrations.Remove(handle);
+                }
+
+                if (deregistrationException != null)
+                {
+                    ExceptionDispatchInfo.Capture(deregistrationException).Throw();
+                }
+            }
+
+            // Drop the matching staged registration and metadata so a later
+            // Disable()/Enable() cycle does not silently re-register the
+            // handler we were just asked to remove.
+            RemoveRegistrationState(handle);
+        }
+
+        // Holds the live de-registration Actions for a single handle in the MULTI-de-registration
+        // case (2+). The common case is EXACTLY ONE de-registration per handle (a staging function
+        // registers once and returns one de-registration Action); that single Action is stored
+        // INLINE as the _deregistrations dictionary value, so the common path allocates no
+        // PendingDeregistration object at all (see AddDeregistration / InvokeDeregistration). This
+        // holder is allocated only when a rare second de-registration accumulates on the same
+        // handle -- a re-entrant retarget-recovery replay can stage one beyond the rollback
+        // baseline -- at which point the inline Action is promoted into this holder's inline head
+        // and the second spills to a lazily-allocated overflow list. This stays a class (mutated in
+        // place through the _deregistrations dictionary), so reference semantics and every
+        // call site are unchanged; only the storage shape changed.
+        //
+        // Invariant: when Count > 0 the head lives in _hasHead/_head and is the LOGICAL
+        // FIRST entry; any further entries follow in _overflow in insertion order. Add
+        // appends to the logical tail; InvokeFrom invokes a contiguous logical tail
+        // [startIndex..Count), removing each success and KEEPING each failure (retryable),
+        // then promotes the first surviving overflow entry into the head slot if the head
+        // was consumed -- preserving the exact ordering, partial-failure, and
+        // rollback-baseline (startIndex) semantics the List<Action> form had.
+        private sealed class PendingDeregistration
+        {
+            private MessageHandler.HandlerDeregistration _head;
+            private bool _hasHead;
+            private List<MessageHandler.HandlerDeregistration> _overflow;
+
+            internal int Count => (_hasHead ? 1 : 0) + (_overflow?.Count ?? 0);
+
+            internal void Add(MessageHandler.HandlerDeregistration action)
+            {
+                // Fill the inline head ONLY when nothing is stored. The empty-overflow
+                // clause matters during the transient window inside InvokeFrom where the
+                // head has been consumed but overflow survivors remain (before they are
+                // promoted): a re-entrant Add then appends to the logical TAIL (overflow),
+                // exactly as the List form did, rather than jumping the new entry ahead of
+                // the survivors into the head slot. The overflow loop re-reads its Count,
+                // so such a tail-appended entry is still invoked in the same pass -- the
+                // List form's behavior preserved. (The stored Actions are pure bus
+                // de-registration callbacks, so this re-entrancy is not reachable through
+                // the public API today; the guard keeps the invariant honest regardless.)
+                if (!_hasHead && (_overflow == null || _overflow.Count == 0))
+                {
+                    _head = action;
+                    _hasHead = true;
+                    return;
+                }
+
+                (_overflow ??= new List<MessageHandler.HandlerDeregistration>()).Add(action);
+            }
+
+            internal Exception InvokeFrom(int startIndex)
+            {
+                if (startIndex < 0)
+                {
+                    startIndex = 0;
+                }
+
+                Exception firstException = null;
+
+                // Logical index 0 is the inline head; logical indices 1.. are _overflow.
+                // Invoke the head only when it is within the requested tail (a rollback
+                // pass with startIndex > 0 must leave the baseline head untouched).
+                if (_hasHead && startIndex <= 0)
+                {
+                    try
+                    {
+                        _head?.Deregister();
+                        _head = null;
+                        _hasHead = false;
+                    }
+                    catch (Exception exception)
+                    {
+                        // Keep the failed head (retryable), exactly as the List form did
+                        // by advancing past a throwing entry instead of removing it.
+                        firstException ??= exception;
+                    }
+                }
+
+                if (_overflow is { Count: > 0 })
+                {
+                    // Overflow entry j has logical index 1 + j; invoke those at or past
+                    // startIndex. Remove successes, keep failures (retryable).
+                    int overflowStart = startIndex <= 1 ? 0 : startIndex - 1;
+                    for (int j = overflowStart; j < _overflow.Count; )
+                    {
+                        try
+                        {
+                            _overflow[j]?.Deregister();
+                            _overflow.RemoveAt(j);
+                        }
+                        catch (Exception exception)
+                        {
+                            firstException ??= exception;
+                            ++j;
+                        }
+                    }
+                }
+
+                // If the head was consumed but overflow survivors remain, promote the
+                // first survivor into the head slot so the head is always the logical
+                // first entry (keeping Count and future Adds consistent).
+                if (!_hasHead && _overflow is { Count: > 0 })
+                {
+                    _head = _overflow[0];
+                    _hasHead = true;
+                    _overflow.RemoveAt(0);
+                }
+
+                return firstException;
+            }
+        }
+
+        // Discriminates the per-handle Registration object's behaviour. Each value
+        // pins (a) which MessageHandler.Register* method the kind-switch in
+        // Registration.Register() calls and (b) which augmented-invoker body shape
+        // (user-delegate type + by-value vs by-ref call) the bound FastHandler/
+        // FastHandlerWithContext delegate runs. The values map 1:1 onto the former
+        // per-method staging lambdas; the *Action / *Fast suffix mirrors the two
+        // public overloads (Action<T>/Action<InstanceId,T> vs FastHandler<T>/
+        // FastHandlerWithContext<T>) that previously had distinct AugmentedHandler
+        // local functions.
+        private enum RegistrationKind
+        {
+            TargetedHandlerAction,
+            TargetedHandlerFast,
+            TargetedPostProcessorAction,
+            TargetedPostProcessorFast,
+            TargetedWithoutTargetingAction,
+            TargetedWithoutTargetingFast,
+            TargetedWithoutTargetingPostProcessorAction,
+            TargetedWithoutTargetingPostProcessorFast,
+            TargetedInterceptor,
+
+            UntargetedHandlerAction,
+            UntargetedHandlerFast,
+            UntargetedPostProcessorFast,
+            UntargetedInterceptor,
+
+            BroadcastHandlerAction,
+            BroadcastHandlerFast,
+            BroadcastPostProcessorAction,
+            BroadcastPostProcessorFast,
+            BroadcastWithoutSourceAction,
+            BroadcastWithoutSourceFast,
+            BroadcastWithoutSourcePostProcessorAction,
+            BroadcastWithoutSourcePostProcessorFast,
+            BroadcastInterceptor,
+
+            GlobalAcceptAllAction,
+            GlobalAcceptAllFast,
+        }
+
+        // The unified per-handle staging object. Replaces, per registration, the old
+        // staging Func<handle, HandlerDeregistration> display class + delegate AND the
+        // nested AugmentedHandler local-function delegate. The captured staging state
+        // (owning token, handle, user handler delegate, target/source InstanceId,
+        // priority, kind) lives in plain fields; the diagnostics-augmented invoker is
+        // an instance method bound to this object (so MessageHandler still receives a
+        // delegate on the hot path -- no virtual/interface call per dispatch).
+        //
+        // The base is non-generic so _registrations / the replay queue can hold every
+        // registration polymorphically. The constrained MessageHandler.Register*<T>
+        // calls each require T : ITargetedMessage / IUntargetedMessage /
+        // IBroadcastMessage, which a single Registration<T> (T : IMessage) cannot
+        // satisfy; the three concrete subclasses below carry the matching constraint
+        // and each run a kind-SWITCH over only the kinds in their family (per the
+        // user-accepted "unified object, accept the kind-switch" design -- NOT ~14
+        // subclasses). GlobalAcceptAllRegistration is non-generic (its sub-handlers
+        // are the fixed IMessage facades).
+        private abstract class Registration
+        {
+            protected readonly MessageRegistrationToken Token;
+            public MessageRegistrationHandle Handle;
+
+            protected Registration(MessageRegistrationToken token)
+            {
+                Token = token;
+            }
+
+            // Kind-switch: (re)register on the bus and return the matching
+            // HandlerDeregistration, exactly as the former staging lambda did. Reads
+            // the token's CURRENT _messageBus (so Enable()/RetargetMessageBus replay
+            // binds to the active bus, unchanged from when _messageBus was captured by
+            // the staging closure at call time -- the staging closure also read the
+            // field, not a snapshot).
+            public abstract MessageHandler.HandlerDeregistration Register();
+        }
+
+        private sealed class TargetedRegistration<T> : Registration
+            where T : ITargetedMessage
+        {
+            private readonly RegistrationKind _kind;
+            private readonly InstanceId _context;
+            private readonly object _userHandler;
+            private readonly int _priority;
+
+            // Strongly-typed views of _userHandler, resolved ONCE at Register() time
+            // (cold) so the per-dispatch augmented invoker calls a typed field directly
+            // -- no per-dispatch castclass or kind-switch (which would add an O(handlers)
+            // cost on the hot dispatch path). Exactly one is set per registration kind.
+            private Action<T> _scalarAction;
+            private MessageHandler.FastHandler<T> _scalarFast;
+            private Action<InstanceId, T> _contextAction;
+            private MessageHandler.FastHandlerWithContext<T> _contextFast;
+
+            internal TargetedRegistration(
+                MessageRegistrationToken token,
+                RegistrationKind kind,
+                InstanceId context,
+                object userHandler,
+                int priority
+            )
+                : base(token)
+            {
+                _kind = kind;
+                _context = context;
+                _userHandler = userHandler;
+                _priority = priority;
+            }
+
+            public override MessageHandler.HandlerDeregistration Register()
+            {
+                MessageHandler messageHandler = Token._messageHandler;
+                IMessageBus messageBus = Token._messageBus;
+                switch (_kind)
+                {
+                    case RegistrationKind.TargetedHandlerAction:
+                        _scalarAction = (Action<T>)_userHandler;
+                        return messageHandler.RegisterTargetedMessageHandler(
+                            _context,
+                            _scalarAction,
+                            AugmentedScalarAction,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    case RegistrationKind.TargetedHandlerFast:
+                        _scalarFast = (MessageHandler.FastHandler<T>)_userHandler;
+                        return messageHandler.RegisterTargetedMessageHandler(
+                            _context,
+                            _scalarFast,
+                            AugmentedScalarFast,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    case RegistrationKind.TargetedPostProcessorAction:
+                        _scalarAction = (Action<T>)_userHandler;
+                        return messageHandler.RegisterTargetedPostProcessor(
+                            _context,
+                            _scalarAction,
+                            AugmentedScalarAction,
+                            _priority,
+                            messageBus
+                        );
+                    case RegistrationKind.TargetedPostProcessorFast:
+                        _scalarFast = (MessageHandler.FastHandler<T>)_userHandler;
+                        return messageHandler.RegisterTargetedPostProcessor(
+                            _context,
+                            _scalarFast,
+                            AugmentedScalarFast,
+                            _priority,
+                            messageBus
+                        );
+                    case RegistrationKind.TargetedWithoutTargetingAction:
+                        _contextAction = (Action<InstanceId, T>)_userHandler;
+                        return messageHandler.RegisterTargetedWithoutTargeting(
+                            _contextAction,
+                            AugmentedContextAction,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    case RegistrationKind.TargetedWithoutTargetingFast:
+                        _contextFast = (MessageHandler.FastHandlerWithContext<T>)_userHandler;
+                        return messageHandler.RegisterTargetedWithoutTargeting(
+                            _contextFast,
+                            AugmentedContextFast,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    case RegistrationKind.TargetedWithoutTargetingPostProcessorAction:
+                        _contextAction = (Action<InstanceId, T>)_userHandler;
+                        return messageHandler.RegisterTargetedWithoutTargetingPostProcessor(
+                            _contextAction,
+                            AugmentedContextAction,
+                            _priority,
+                            messageBus
+                        );
+                    case RegistrationKind.TargetedWithoutTargetingPostProcessorFast:
+                        _contextFast = (MessageHandler.FastHandlerWithContext<T>)_userHandler;
+                        return messageHandler.RegisterTargetedWithoutTargetingPostProcessor(
+                            _contextFast,
+                            AugmentedContextFast,
+                            _priority,
+                            messageBus
+                        );
+                    case RegistrationKind.TargetedInterceptor:
+                        return messageHandler.RegisterTargetedInterceptor(
+                            (IMessageBus.TargetedInterceptor<T>)_userHandler,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    default:
+                        throw new InvalidOperationException(
+                            $"Unexpected registration kind {_kind} for TargetedRegistration<{typeof(T)}>."
+                        );
+                }
+            }
+
+            // Scalar invokers (targeted handler / post-processor). The user's handler is
+            // the identity/dedup key; this flat invoker runs for the default slot. Calls
+            // the typed field directly (no castclass) then records the (message, _context)
+            // emission, matching the former AugmentedHandler bodies exactly.
+            private void AugmentedScalarAction(ref T message)
+            {
+                _scalarAction(message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message, _context));
+                }
+            }
+
+            private void AugmentedScalarFast(ref T message)
+            {
+                _scalarFast(ref message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message, _context));
+                }
+            }
+
+            // Context invokers (without-targeting handler / post-processor). Emission data
+            // uses the dispatch-supplied target (the ref param), not the stored _context
+            // (default for these kinds), matching the former bodies exactly.
+            private void AugmentedContextAction(ref InstanceId target, ref T message)
+            {
+                _contextAction(target, message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message, target));
+                }
+            }
+
+            private void AugmentedContextFast(ref InstanceId target, ref T message)
+            {
+                _contextFast(ref target, ref message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message, target));
+                }
+            }
+        }
+
+        private sealed class UntargetedRegistration<T> : Registration
+            where T : IUntargetedMessage
+        {
+            private readonly RegistrationKind _kind;
+            private readonly object _userHandler;
+            private readonly int _priority;
+
+            // Typed views of _userHandler, resolved once at Register() time (cold) so the
+            // per-dispatch invoker calls a typed field directly -- no castclass/switch on
+            // the hot path. Exactly one is set per registration kind.
+            private Action<T> _scalarAction;
+            private MessageHandler.FastHandler<T> _scalarFast;
+
+            internal UntargetedRegistration(
+                MessageRegistrationToken token,
+                RegistrationKind kind,
+                object userHandler,
+                int priority
+            )
+                : base(token)
+            {
+                _kind = kind;
+                _userHandler = userHandler;
+                _priority = priority;
+            }
+
+            public override MessageHandler.HandlerDeregistration Register()
+            {
+                MessageHandler messageHandler = Token._messageHandler;
+                IMessageBus messageBus = Token._messageBus;
+                switch (_kind)
+                {
+                    case RegistrationKind.UntargetedHandlerAction:
+                        _scalarAction = (Action<T>)_userHandler;
+                        return messageHandler.RegisterUntargetedMessageHandler(
+                            _scalarAction,
+                            AugmentedScalarAction,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    case RegistrationKind.UntargetedHandlerFast:
+                        _scalarFast = (MessageHandler.FastHandler<T>)_userHandler;
+                        return messageHandler.RegisterUntargetedMessageHandler(
+                            _scalarFast,
+                            AugmentedScalarFast,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    case RegistrationKind.UntargetedPostProcessorFast:
+                        _scalarFast = (MessageHandler.FastHandler<T>)_userHandler;
+                        return messageHandler.RegisterUntargetedPostProcessor(
+                            _scalarFast,
+                            AugmentedScalarFast,
+                            _priority,
+                            messageBus
+                        );
+                    case RegistrationKind.UntargetedInterceptor:
+                        return messageHandler.RegisterUntargetedInterceptor(
+                            (IMessageBus.UntargetedInterceptor<T>)_userHandler,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    default:
+                        throw new InvalidOperationException(
+                            $"Unexpected registration kind {_kind} for UntargetedRegistration<{typeof(T)}>."
+                        );
+                }
+            }
+
+            // Untargeted scalar invokers. No context: emission data carries the message
+            // only, matching the former AugmentedHandler bodies exactly.
+            private void AugmentedScalarAction(ref T message)
+            {
+                _scalarAction(message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message));
+                }
+            }
+
+            private void AugmentedScalarFast(ref T message)
+            {
+                _scalarFast(ref message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message));
+                }
+            }
+        }
+
+        private sealed class BroadcastRegistration<T> : Registration
+            where T : IBroadcastMessage
+        {
+            private readonly RegistrationKind _kind;
+            private readonly InstanceId _context;
+            private readonly object _userHandler;
+            private readonly int _priority;
+
+            // Typed views of _userHandler, resolved once at Register() time (cold) so the
+            // per-dispatch invoker calls a typed field directly -- no castclass/switch on
+            // the hot path. Exactly one is set per registration kind.
+            private Action<T> _scalarAction;
+            private MessageHandler.FastHandler<T> _scalarFast;
+            private Action<InstanceId, T> _contextAction;
+            private MessageHandler.FastHandlerWithContext<T> _contextFast;
+
+            internal BroadcastRegistration(
+                MessageRegistrationToken token,
+                RegistrationKind kind,
+                InstanceId context,
+                object userHandler,
+                int priority
+            )
+                : base(token)
+            {
+                _kind = kind;
+                _context = context;
+                _userHandler = userHandler;
+                _priority = priority;
+            }
+
+            public override MessageHandler.HandlerDeregistration Register()
+            {
+                MessageHandler messageHandler = Token._messageHandler;
+                IMessageBus messageBus = Token._messageBus;
+                switch (_kind)
+                {
+                    case RegistrationKind.BroadcastHandlerAction:
+                        _scalarAction = (Action<T>)_userHandler;
+                        return messageHandler.RegisterSourcedBroadcastMessageHandler(
+                            _context,
+                            _scalarAction,
+                            AugmentedScalarAction,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    case RegistrationKind.BroadcastHandlerFast:
+                        _scalarFast = (MessageHandler.FastHandler<T>)_userHandler;
+                        return messageHandler.RegisterSourcedBroadcastMessageHandler(
+                            _context,
+                            _scalarFast,
+                            AugmentedScalarFast,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    case RegistrationKind.BroadcastPostProcessorAction:
+                        _scalarAction = (Action<T>)_userHandler;
+                        return messageHandler.RegisterSourcedBroadcastPostProcessor(
+                            _context,
+                            _scalarAction,
+                            AugmentedScalarAction,
+                            _priority,
+                            messageBus
+                        );
+                    case RegistrationKind.BroadcastPostProcessorFast:
+                        _scalarFast = (MessageHandler.FastHandler<T>)_userHandler;
+                        return messageHandler.RegisterSourcedBroadcastPostProcessor(
+                            _context,
+                            _scalarFast,
+                            AugmentedScalarFast,
+                            _priority,
+                            messageBus
+                        );
+                    case RegistrationKind.BroadcastWithoutSourceAction:
+                        _contextAction = (Action<InstanceId, T>)_userHandler;
+                        return messageHandler.RegisterSourcedBroadcastWithoutSource(
+                            _contextAction,
+                            AugmentedContextAction,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    case RegistrationKind.BroadcastWithoutSourceFast:
+                        _contextFast = (MessageHandler.FastHandlerWithContext<T>)_userHandler;
+                        return messageHandler.RegisterSourcedBroadcastWithoutSource(
+                            _contextFast,
+                            AugmentedContextFast,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    case RegistrationKind.BroadcastWithoutSourcePostProcessorAction:
+                        _contextAction = (Action<InstanceId, T>)_userHandler;
+                        return messageHandler.RegisterSourcedBroadcastWithoutSourcePostProcessor(
+                            _contextAction,
+                            AugmentedContextAction,
+                            priority: _priority,
+                            messageBus
+                        );
+                    case RegistrationKind.BroadcastWithoutSourcePostProcessorFast:
+                        _contextFast = (MessageHandler.FastHandlerWithContext<T>)_userHandler;
+                        return messageHandler.RegisterSourcedBroadcastWithoutSourcePostProcessor(
+                            _contextFast,
+                            AugmentedContextFast,
+                            priority: _priority,
+                            messageBus
+                        );
+                    case RegistrationKind.BroadcastInterceptor:
+                        return messageHandler.RegisterBroadcastInterceptor(
+                            (IMessageBus.BroadcastInterceptor<T>)_userHandler,
+                            priority: _priority,
+                            messageBus: messageBus
+                        );
+                    default:
+                        throw new InvalidOperationException(
+                            $"Unexpected registration kind {_kind} for BroadcastRegistration<{typeof(T)}>."
+                        );
+                }
+            }
+
+            // Broadcast scalar invokers. Emission data carries the stored source
+            // (_context), matching the former AugmentedHandler bodies exactly.
+            private void AugmentedScalarAction(ref T message)
+            {
+                _scalarAction(message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message, _context));
+                }
+            }
+
+            private void AugmentedScalarFast(ref T message)
+            {
+                _scalarFast(ref message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message, _context));
+                }
+            }
+
+            // Broadcast context invokers for the without-source kinds. Emission data uses
+            // the dispatch-supplied source (the ref param), not the stored _context
+            // (default for these kinds), matching the former bodies exactly.
+            private void AugmentedContextAction(ref InstanceId source, ref T message)
+            {
+                _contextAction(source, message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message, source));
+                }
+            }
+
+            private void AugmentedContextFast(ref InstanceId source, ref T message)
+            {
+                _contextFast(ref source, ref message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message, source));
+                }
+            }
+        }
+
+        // Global accept-all is non-generic: its three sub-handlers are the fixed
+        // IMessage facades. Stores the three user delegates (as object, since the two
+        // public overloads differ in delegate shape -- Action vs FastHandler/
+        // FastHandlerWithContext) and exposes six augmented sub-invokers (three per
+        // overload shape). The kind-switch picks the matching MessageHandler.
+        // RegisterGlobalAcceptAll overload and binds the three augmented invokers.
+        private sealed class GlobalAcceptAllRegistration : Registration
+        {
+            private readonly RegistrationKind _kind;
+
+            // Typed sub-handlers (one shape-trio is set per kind). The per-dispatch
+            // invokers call these directly -- no castclass on the hot global-dispatch
+            // path (the heaviest fan-out, so the castclass cost there was the worst).
+            private readonly Action<IUntargetedMessage> _untargetedAction;
+            private readonly Action<InstanceId, ITargetedMessage> _targetedAction;
+            private readonly Action<InstanceId, IBroadcastMessage> _broadcastAction;
+            private readonly MessageHandler.FastHandler<IUntargetedMessage> _untargetedFast;
+            private readonly MessageHandler.FastHandlerWithContext<ITargetedMessage> _targetedFast;
+            private readonly MessageHandler.FastHandlerWithContext<IBroadcastMessage> _broadcastFast;
+
+            internal GlobalAcceptAllRegistration(
+                MessageRegistrationToken token,
+                Action<IUntargetedMessage> untargeted,
+                Action<InstanceId, ITargetedMessage> targeted,
+                Action<InstanceId, IBroadcastMessage> broadcast
+            )
+                : base(token)
+            {
+                _kind = RegistrationKind.GlobalAcceptAllAction;
+                _untargetedAction = untargeted;
+                _targetedAction = targeted;
+                _broadcastAction = broadcast;
+            }
+
+            internal GlobalAcceptAllRegistration(
+                MessageRegistrationToken token,
+                MessageHandler.FastHandler<IUntargetedMessage> untargeted,
+                MessageHandler.FastHandlerWithContext<ITargetedMessage> targeted,
+                MessageHandler.FastHandlerWithContext<IBroadcastMessage> broadcast
+            )
+                : base(token)
+            {
+                _kind = RegistrationKind.GlobalAcceptAllFast;
+                _untargetedFast = untargeted;
+                _targetedFast = targeted;
+                _broadcastFast = broadcast;
+            }
+
+            public override MessageHandler.HandlerDeregistration Register()
+            {
+                MessageHandler messageHandler = Token._messageHandler;
+                IMessageBus messageBus = Token._messageBus;
+                if (_kind == RegistrationKind.GlobalAcceptAllAction)
+                {
+                    return messageHandler.RegisterGlobalAcceptAll(
+                        _untargetedAction,
+                        AugmentedUntargetedAction,
+                        _targetedAction,
+                        AugmentedTargetedAction,
+                        _broadcastAction,
+                        AugmentedBroadcastAction,
+                        messageBus
+                    );
+                }
+
+                return messageHandler.RegisterGlobalAcceptAll(
+                    _untargetedFast,
+                    AugmentedUntargetedFast,
+                    _targetedFast,
+                    AugmentedTargetedFast,
+                    _broadcastFast,
+                    AugmentedBroadcastFast,
+                    messageBus
+                );
+            }
+
+            private void AugmentedUntargetedAction(IUntargetedMessage message)
+            {
+                _untargetedAction(message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message));
+                }
+            }
+
+            private void AugmentedTargetedAction(InstanceId target, ITargetedMessage message)
+            {
+                _targetedAction(target, message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message, target));
+                }
+            }
+
+            private void AugmentedBroadcastAction(InstanceId source, IBroadcastMessage message)
+            {
+                _broadcastAction(source, message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message, source));
+                }
+            }
+
+            private void AugmentedUntargetedFast(ref IUntargetedMessage message)
+            {
+                _untargetedFast(ref message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message));
+                }
+            }
+
+            private void AugmentedTargetedFast(ref InstanceId target, ref ITargetedMessage message)
+            {
+                _targetedFast(ref target, ref message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message, target));
+                }
+            }
+
+            private void AugmentedBroadcastFast(
+                ref InstanceId source,
+                ref IBroadcastMessage message
+            )
+            {
+                _broadcastFast(ref source, ref message);
+                if (Token._diagnosticMode)
+                {
+                    Token._callCounts[Handle] = Token._callCounts.GetValueOrDefault(Handle) + 1;
+                    Token._emissionBuffer.Add(new MessageEmissionData(message, source));
+                }
+            }
         }
 
         /// <summary>
@@ -2052,7 +2907,7 @@ namespace DxMessaging.Core
         }
 
         /// <summary>
-        /// Removes all staged registrations and releases references to the handler.
+        /// Removes all staged registrations and clears token-local diagnostic state.
         /// </summary>
         public void Dispose()
         {