com.wallstop-studios.dxmessaging 2.2.0 → 3.1.0

package/Runtime/Unity/Integrations/VContainer/VContainerRegistrationExtensions.cs

@@ -2,22 +2,127 @@
 namespace DxMessaging.Unity.Integrations.VContainer
 {
 #if VCONTAINER_PRESENT
+    using System;
     using global::VContainer;
     using Core.MessageBus;
+    using Core.Pooling;
 
     /// <summary>
-    /// Provides convenience extension methods for wiring <see cref="IMessageRegistrationBuilder"/> inside VContainer scopes.
+    /// Provides convenience extension methods for wiring DxMessaging services inside
+    /// VContainer scopes. The helper covers the bus registration as well as the
+    /// <see cref="IMessageRegistrationBuilder"/> binding so consumers do not have to
+    /// drive VContainer reflection-based constructor selection on internal types.
     /// </summary>
     public static class VContainerRegistrationExtensions
     {
+        /// <summary>
+        /// Registers a <see cref="MessageBus"/> exposed as itself and
+        /// <see cref="IMessageBus"/> using an explicit factory backed by the
+        /// parameterless <see cref="MessageBus"/> constructor. VContainer's
+        /// <c>TypeAnalyzer</c> scans both public and non-public constructors using
+        /// <c>BindingFlags.Public | BindingFlags.NonPublic</c>, so the bare
+        /// <c>Register&lt;MessageBus&gt;(Lifetime.Singleton).As&lt;IMessageBus&gt;()</c>
+        /// pattern would still latch onto a clock-taking private overload whose
+        /// <see cref="IDxMessagingClock"/> dependency is not registered. Always prefer this
+        /// helper. Calling this helper alongside a bare bus registration raises a
+        /// <c>VContainerException</c> at <see cref="IContainerBuilder.Build"/> time.
+        /// </summary>
+        /// <param name="builder">Container builder receiving the registration.</param>
+        /// <param name="lifetime">Lifetime to assign to the registration. Defaults to <see cref="Lifetime.Singleton"/>.</param>
+        /// <returns>The underlying registration builder for further chaining.</returns>
+        public static RegistrationBuilder RegisterDxMessagingBus(
+            this IContainerBuilder builder,
+            Lifetime lifetime = Lifetime.Singleton
+        )
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
+            return builder
+                .Register<MessageBus>(CreateMessageBus, lifetime)
+                .As(typeof(MessageBus), typeof(IMessageBus));
+        }
+
+        /// <summary>
+        /// Registers a <see cref="MessageBus"/> exposed as itself and
+        /// <see cref="IMessageBus"/> using the supplied factory. Use this overload when
+        /// callers need to inject a custom <see cref="IDxMessagingClock"/> (for example a
+        /// deterministic test clock) or configure eviction options through
+        /// <see cref="MessageBus.CreateForInternalUse"/>.
+        /// </summary>
+        /// <param name="builder">Container builder receiving the registration.</param>
+        /// <param name="factory">Delegate that constructs the <see cref="MessageBus"/> instance using the resolver.</param>
+        /// <param name="lifetime">Lifetime to assign to the registration. Defaults to <see cref="Lifetime.Singleton"/>.</param>
+        /// <returns>The underlying registration builder for further chaining.</returns>
+        public static RegistrationBuilder RegisterDxMessagingBus(
+            this IContainerBuilder builder,
+            Func<IObjectResolver, MessageBus> factory,
+            Lifetime lifetime = Lifetime.Singleton
+        )
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+            if (factory == null)
+            {
+                throw new ArgumentNullException(nameof(factory));
+            }
+            return builder
+                .Register<MessageBus>(factory, lifetime)
+                .As(typeof(MessageBus), typeof(IMessageBus));
+        }
+
+        /// <summary>
+        /// Registers a <see cref="MessageBus"/> exposed as itself and
+        /// <see cref="IMessageBus"/> using the supplied <see cref="IDxMessagingClock"/>.
+        /// Builds the bus through <see cref="MessageBus.CreateForInternalUse"/>, which
+        /// is visible to the integration assembly via <c>InternalsVisibleTo</c>.
+        /// </summary>
+        /// <param name="builder">Container builder receiving the registration.</param>
+        /// <param name="clock">Clock implementation injected into the bus. Must not be null.</param>
+        /// <param name="lifetime">Lifetime to assign to the registration. Defaults to <see cref="Lifetime.Singleton"/>.</param>
+        /// <returns>The underlying registration builder for further chaining.</returns>
+        public static RegistrationBuilder RegisterDxMessagingBus(
+            this IContainerBuilder builder,
+            IDxMessagingClock clock,
+            Lifetime lifetime = Lifetime.Singleton
+        )
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+            if (clock == null)
+            {
+                throw new ArgumentNullException(nameof(clock));
+            }
+            return builder
+                .Register<MessageBus>(_ => MessageBus.CreateForInternalUse(clock), lifetime)
+                .As(typeof(MessageBus), typeof(IMessageBus));
+        }
+
         /// <summary>
         /// Registers <see cref="IMessageRegistrationBuilder"/> as a transient service backed by the scoped message bus.
         /// </summary>
+        /// <param name="builder">Container builder receiving the registration.</param>
         public static void RegisterMessageRegistrationBuilder(this IContainerBuilder builder)
         {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
             builder.Register<IMessageRegistrationBuilder>(CreateBuilder, Lifetime.Transient);
         }
 
+        private static MessageBus CreateMessageBus(IObjectResolver resolver)
+        {
+            return new MessageBus();
+        }
+
         private static IMessageRegistrationBuilder CreateBuilder(IObjectResolver resolver)
         {
             if (resolver.TryResolve(out IMessageBusProvider provider))
@@ -28,6 +133,9 @@ namespace DxMessaging.Unity.Integrations.VContainer
             return new MessageRegistrationBuilder(new ResolverMessageBusProvider(resolver));
         }
 
+        /// <summary>
+        /// Wraps a VContainer <see cref="IObjectResolver"/> as an <see cref="IMessageBusProvider"/>.
+        /// </summary>
         public sealed class ResolverMessageBusProvider : IMessageBusProvider
         {
             private readonly IObjectResolver _resolver;

package/Runtime/Unity/Integrations/VContainer/VContainerRegistrationExtensions.cs.meta

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: 494e388075f84aeda9266a0e57f8a05d
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 494e388075f84aeda9266a0e57f8a05d
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Unity/Integrations/VContainer/WallstopStudios.DxMessaging.VContainer.asmdef

@@ -1,30 +1,30 @@
-{
-  "name": "WallstopStudios.DxMessaging.VContainer",
-  "rootNamespace": "DxMessaging.Unity.Integrations.VContainer",
-  "references": ["WallstopStudios.DxMessaging", "VContainer", "VContainer.Unity"],
-  "includePlatforms": [],
-  "excludePlatforms": [],
-  "allowUnsafeCode": false,
-  "overrideReferences": false,
-  "precompiledReferences": [],
-  "autoReferenced": true,
-  "defineConstraints": ["VCONTAINER_PRESENT"],
-  "versionDefines": [
-    {
-      "name": "jp.cysharp.vcontainer",
-      "expression": "0.0.1",
-      "define": "VCONTAINER_PRESENT"
-    },
-    {
-      "name": "jp.hadashikick.vcontainer",
-      "expression": "0.0.1",
-      "define": "VCONTAINER_PRESENT"
-    },
-    {
-      "name": "VContainer",
-      "expression": "0.0.1",
-      "define": "VCONTAINER_PRESENT"
-    }
-  ],
-  "noEngineReferences": false
-}
+{
+  "name": "WallstopStudios.DxMessaging.VContainer",
+  "rootNamespace": "DxMessaging.Unity.Integrations.VContainer",
+  "references": ["WallstopStudios.DxMessaging", "VContainer", "VContainer.Unity"],
+  "includePlatforms": [],
+  "excludePlatforms": [],
+  "allowUnsafeCode": false,
+  "overrideReferences": false,
+  "precompiledReferences": [],
+  "autoReferenced": true,
+  "defineConstraints": ["VCONTAINER_PRESENT"],
+  "versionDefines": [
+    {
+      "name": "jp.cysharp.vcontainer",
+      "expression": "0.0.1",
+      "define": "VCONTAINER_PRESENT"
+    },
+    {
+      "name": "jp.hadashikick.vcontainer",
+      "expression": "0.0.1",
+      "define": "VCONTAINER_PRESENT"
+    },
+    {
+      "name": "VContainer",
+      "expression": "0.0.1",
+      "define": "VCONTAINER_PRESENT"
+    }
+  ],
+  "noEngineReferences": false
+}

package/Runtime/Unity/Integrations/VContainer/WallstopStudios.DxMessaging.VContainer.asmdef.meta

@@ -1,7 +1,7 @@
-fileFormatVersion: 2
-guid: 2583d1d4ebd847faba751e3be6bf5b20
-AssemblyDefinitionImporter:
-  externalObjects: {}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 2583d1d4ebd847faba751e3be6bf5b20
+AssemblyDefinitionImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Unity/Integrations/VContainer.meta

@@ -1,8 +1,8 @@
-fileFormatVersion: 2
-guid: 4d890fb7cb4f49e18fd9fbac12d5040c
-folderAsset: yes
-DefaultImporter:
-  externalObjects: {}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 4d890fb7cb4f49e18fd9fbac12d5040c
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Unity/Integrations/Zenject/AssemblyInfo.cs.meta

@@ -1,3 +1,11 @@
-fileFormatVersion: 2
-guid: ec21f9c7970043fe88177114708ef79e
-timeCreated: 1761517466
+fileFormatVersion: 2
+guid: ec21f9c7970043fe88177114708ef79e
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Runtime/Unity/Integrations/Zenject/WallstopStudios.DxMessaging.Zenject.asmdef

@@ -1,30 +1,30 @@
-{
-  "name": "WallstopStudios.DxMessaging.Zenject",
-  "rootNamespace": "DxMessaging.Unity.Integrations.Zenject",
-  "references": ["WallstopStudios.DxMessaging", "Zenject"],
-  "includePlatforms": [],
-  "excludePlatforms": [],
-  "allowUnsafeCode": false,
-  "overrideReferences": false,
-  "precompiledReferences": [],
-  "autoReferenced": true,
-  "defineConstraints": ["ZENJECT_PRESENT"],
-  "versionDefines": [
-    {
-      "name": "com.extenject.zenject",
-      "expression": "0.0.1",
-      "define": "ZENJECT_PRESENT"
-    },
-    {
-      "name": "com.modesttree.zenject",
-      "expression": "0.0.1",
-      "define": "ZENJECT_PRESENT"
-    },
-    {
-      "name": "com.svermeulen.extenject",
-      "expression": "0.0.1",
-      "define": "ZENJECT_PRESENT"
-    }
-  ],
-  "noEngineReferences": false
-}
+{
+  "name": "WallstopStudios.DxMessaging.Zenject",
+  "rootNamespace": "DxMessaging.Unity.Integrations.Zenject",
+  "references": ["WallstopStudios.DxMessaging", "Zenject"],
+  "includePlatforms": [],
+  "excludePlatforms": [],
+  "allowUnsafeCode": false,
+  "overrideReferences": false,
+  "precompiledReferences": [],
+  "autoReferenced": true,
+  "defineConstraints": ["ZENJECT_PRESENT"],
+  "versionDefines": [
+    {
+      "name": "com.extenject.zenject",
+      "expression": "0.0.1",
+      "define": "ZENJECT_PRESENT"
+    },
+    {
+      "name": "com.modesttree.zenject",
+      "expression": "0.0.1",
+      "define": "ZENJECT_PRESENT"
+    },
+    {
+      "name": "com.svermeulen.extenject",
+      "expression": "0.0.1",
+      "define": "ZENJECT_PRESENT"
+    }
+  ],
+  "noEngineReferences": false
+}

package/Runtime/Unity/Integrations/Zenject/WallstopStudios.DxMessaging.Zenject.asmdef.meta

@@ -1,7 +1,7 @@
-fileFormatVersion: 2
-guid: 5c2f6b45062a4c07a599dd8bcbac2bb4
-AssemblyDefinitionImporter:
-  externalObjects: {}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 5c2f6b45062a4c07a599dd8bcbac2bb4
+AssemblyDefinitionImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Unity/Integrations/Zenject/ZenjectRegistrationInstaller.cs

@@ -2,8 +2,10 @@
 namespace DxMessaging.Unity.Integrations.Zenject
 {
 #if ZENJECT_PRESENT
-    using global::Zenject;
+    using System;
     using Core.MessageBus;
+    using Core.Pooling;
+    using global::Zenject;
 
     /// <summary>
     /// Optional installer that exposes <see cref="IMessageRegistrationBuilder"/> using the scoped Zenject container.
@@ -64,6 +66,82 @@ namespace DxMessaging.Unity.Integrations.Zenject
             }
         }
     }
+
+    /// <summary>
+    /// Provides convenience helpers for wiring a <see cref="MessageBus"/> into Zenject containers.
+    /// Zenject's <c>BindInterfacesAndSelfTo</c> defaults to selecting the public parameterless
+    /// constructor, so today the bare <c>Container.BindInterfacesAndSelfTo&lt;MessageBus&gt;().AsSingle()</c>
+    /// pattern resolves correctly. Behaviour is version-sensitive: future Zenject releases that
+    /// broaden constructor scanning could pick a non-public clock-taking overload whose
+    /// dependency is not registered, mirroring the VContainer failure mode -- always prefer the
+    /// helper below for clarity and forward compatibility. Calling this helper alongside an
+    /// existing bare bind raises a Zenject binding-conflict exception when the container is
+    /// validated.
+    /// </summary>
+    public static class ZenjectRegistrationExtensions
+    {
+        /// <summary>
+        /// Binds a singleton <see cref="MessageBus"/> exposed as <see cref="IMessageBus"/> using
+        /// an explicit method, sidestepping reflection-based constructor selection.
+        /// </summary>
+        /// <param name="container">Container receiving the registration.</param>
+        public static void BindDxMessagingBus(this DiContainer container)
+        {
+            if (container == null)
+            {
+                throw new ArgumentNullException(nameof(container));
+            }
+            container
+                .BindInterfacesAndSelfTo<MessageBus>()
+                .FromMethod(_ => new MessageBus())
+                .AsSingle();
+        }
+
+        /// <summary>
+        /// Binds a singleton <see cref="MessageBus"/> exposed as <see cref="IMessageBus"/> using
+        /// the supplied factory. Allows callers to inject a custom <see cref="IDxMessagingClock"/>
+        /// via <see cref="MessageBus.CreateForInternalUse"/>.
+        /// </summary>
+        /// <param name="container">Container receiving the registration.</param>
+        /// <param name="factory">Delegate that constructs the <see cref="MessageBus"/> instance using the inject context.</param>
+        public static void BindDxMessagingBus(
+            this DiContainer container,
+            Func<InjectContext, MessageBus> factory
+        )
+        {
+            if (container == null)
+            {
+                throw new ArgumentNullException(nameof(container));
+            }
+            if (factory == null)
+            {
+                throw new ArgumentNullException(nameof(factory));
+            }
+            container.BindInterfacesAndSelfTo<MessageBus>().FromMethod(factory).AsSingle();
+        }
+
+        /// <summary>
+        /// Binds a singleton <see cref="MessageBus"/> exposed as <see cref="IMessageBus"/> using
+        /// the supplied <see cref="IDxMessagingClock"/>.
+        /// </summary>
+        /// <param name="container">Container receiving the registration.</param>
+        /// <param name="clock">Clock implementation injected into the bus. Must not be null.</param>
+        public static void BindDxMessagingBus(this DiContainer container, IDxMessagingClock clock)
+        {
+            if (container == null)
+            {
+                throw new ArgumentNullException(nameof(container));
+            }
+            if (clock == null)
+            {
+                throw new ArgumentNullException(nameof(clock));
+            }
+            container
+                .BindInterfacesAndSelfTo<MessageBus>()
+                .FromMethod(_ => MessageBus.CreateForInternalUse(clock))
+                .AsSingle();
+        }
+    }
 #endif
 }
 #endif

package/Runtime/Unity/Integrations/Zenject/ZenjectRegistrationInstaller.cs.meta

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: 1f5d2f7d6c9b4bb9bb5d9ce1f2e4763c
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 1f5d2f7d6c9b4bb9bb5d9ce1f2e4763c
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Unity/Integrations/Zenject.meta

@@ -1,8 +1,8 @@
-fileFormatVersion: 2
-guid: 6f2c8f2b1b0b4f618d4f2711d8f6ac2b
-folderAsset: yes
-DefaultImporter:
-  externalObjects: {}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 6f2c8f2b1b0b4f618d4f2711d8f6ac2b
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Unity/Integrations.meta

@@ -1,8 +1,8 @@
-fileFormatVersion: 2
-guid: d4cc934a94a46b849bd0ce328eba12be
-folderAsset: yes
-DefaultImporter:
-  externalObjects: {}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: d4cc934a94a46b849bd0ce328eba12be
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Unity/MessageAwareComponent.cs

@@ -1,6 +1,7 @@
 #if UNITY_2021_3_OR_NEWER
 namespace DxMessaging.Unity
 {
+    using System;
     using Core;
     using Core.MessageBus;
     using Core.Messages;
@@ -18,6 +19,8 @@ namespace DxMessaging.Unity
     /// - <see cref="Awake"/> creates the token and calls <see cref="RegisterMessageHandlers"/>.
     /// - <see cref="OnEnable"/>/<see cref="OnDisable"/> enable/disable the token when
     ///   <see cref="MessageRegistrationTiedToEnableStatus"/> is true.
+    /// - <see cref="OnEnable"/> can additionally re-create a released token when
+    ///   <see cref="ReregisterOnEnableAfterRelease"/> is overridden to true.
     /// - <see cref="OnDestroy"/> disables the token and releases references.
     /// </remarks>
     /// <example>
@@ -60,6 +63,25 @@ namespace DxMessaging.Unity
         /// </summary>
         protected virtual bool MessageRegistrationTiedToEnableStatus => true;
 
+        /// <summary>
+        /// Controls whether enabling this component re-creates its registration token and replays
+        /// <see cref="RegisterMessageHandlers"/> after the token was released (for example via
+        /// <see cref="MessagingComponent.Release"/>).
+        /// </summary>
+        /// <remarks>
+        /// Default <c>false</c>: once released, the component stays unregistered across
+        /// enable/disable cycles until <see cref="MessagingComponent.Create"/> is invoked manually.
+        /// Override to return <c>true</c> to opt into automatic recovery on the next enable:
+        /// if no live token exists, a fresh one is created and <see cref="RegisterMessageHandlers"/>
+        /// replays exactly once; if a manual <see cref="MessagingComponent.Create"/> already minted
+        /// a fresh token since the release, that token is adopted as-is (the manual creator owns
+        /// staging, so nothing is replayed and nothing double-stages).
+        /// When <see cref="MessageRegistrationTiedToEnableStatus"/> is false, the recovery still
+        /// re-creates and stages but does NOT enable the new token; call
+        /// <see cref="MessageRegistrationToken.Enable"/> yourself, exactly as for the original token.
+        /// </remarks>
+        protected virtual bool ReregisterOnEnableAfterRelease => false;
+
         /// <summary>
         /// If true, registers demo handlers for <see cref="Core.Messages.StringMessage"/> and
         /// <see cref="Core.Messages.GlobalStringMessage"/>. Override and return <c>false</c> to disable.
@@ -71,6 +93,15 @@ namespace DxMessaging.Unity
         protected IMessageBusProvider _configuredMessageBusProvider;
         protected MessageBusProviderHandle _configuredMessageBusProviderHandle;
 
+#if UNITY_EDITOR || DEBUG
+        // G6: latch the OnEnable self-check log to fire at most once per component instance.
+        // [NonSerialized] keeps the latch from being saved into the scene; every fresh
+        // instance starts with the latch clear and gets at most one breadcrumb if it really is
+        // missing the base.Awake() call.
+        [NonSerialized]
+        private bool _selfCheckLogged;
+#endif
+
         /// <summary>
         /// Creates the <see cref="MessagingComponent"/>, token, and calls <see cref="RegisterMessageHandlers"/>.
         /// </summary>
@@ -128,13 +159,56 @@ namespace DxMessaging.Unity
 
         /// <summary>
         /// Enables the token if <see cref="MessageRegistrationTiedToEnableStatus"/> is true.
+        /// When <see cref="ReregisterOnEnableAfterRelease"/> is true and the token was released,
+        /// a fresh token is created and <see cref="RegisterMessageHandlers"/> replays first.
         /// </summary>
         protected virtual void OnEnable()
         {
+            if (
+                ReregisterOnEnableAfterRelease
+                && _messageRegistrationToken != null
+                && _messagingComponent != null
+            )
+            {
+                if (_messagingComponent.TryGetToken(this, out MessageRegistrationToken liveToken))
+                {
+                    // A manual MessagingComponent.Create(this) between the release and
+                    // this enable minted a fresh token the field does not know about;
+                    // adopt it so Token/Enable() operate on the live registration. The
+                    // manual creator owns staging in that case, so RegisterMessageHandlers
+                    // is NOT replayed here (no double-staging).
+                    _messageRegistrationToken = liveToken;
+                }
+                else
+                {
+                    _messageRegistrationToken = _messagingComponent.Create(this);
+                    RegisterMessageHandlers();
+                }
+            }
+
             if (MessageRegistrationTiedToEnableStatus)
             {
                 _messageRegistrationToken?.Enable();
             }
+#if UNITY_EDITOR || DEBUG
+            // G6: belt-and-braces self-check. If we got here without a registration token, the
+            // most common cause is a subclass that overrode Awake without calling base.Awake();
+            // the analyzer DXMSG006 catches this at compile time but only if the project loads
+            // the analyzer DLL (e.g. user has disabled analyzers, opened the project on a Unity
+            // version that does not load the DLL, or the analyzer suppressed via attribute /
+            // ignore list). We surface a one-time-per-instance LogError so the failure mode is
+            // not silent. Gated on UNITY_EDITOR || DEBUG so release builds pay zero cost.
+            if (_messageRegistrationToken == null && !_selfCheckLogged)
+            {
+                _selfCheckLogged = true;
+                Debug.LogError(
+                    $"[DxMessaging] {GetType().Name} appears to be missing a base.Awake() call; "
+                        + "no registration token exists, so this component will not receive messages. "
+                        + "See https://github.com/Ambiguous-Interactive/DxMessaging/blob/master/docs/reference/analyzers.md#dxmsg006-missing-base-call",
+                    this
+                );
+            }
+#endif
         }
 
         /// <summary>

package/Runtime/Unity/MessageAwareComponent.cs.meta

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: f0743aa54f7a37f4c985cf9b55f68279
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: f0743aa54f7a37f4c985cf9b55f68279
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: