refactor: address PR #4070 review feedback

- deterministic poll-until in bulk dispatch test (drop Task.Delay)
- document firstMessage invariant in BulkDispatchAsync
- clarify ProducerTopicHeaderName xml doc (bag key, not header)
- braces around single-line if in WrapPipeline + WrapPipelineAsync
- inline note on Log.DecoupledInvocationOfMessage divergence from lookup

Co-Authored-By: Claude (claude-opus-4-7) <noreply@anthropic.com>

Author: Jonny-Freemarket

src/Paramore.Brighter/Message.cs

@@ -51,8 +51,10 @@ public class Message : IEquatable<Message>
         public const string RejectionReasonHeaderName = "RejectionReason";
 
         /// <summary>
-        /// Tag name for the producer topic header, used when the message mapper overrides the topic (e.g. for Reply messages)
-        /// so that the outbox dispatcher can still find the correct producer
+        /// Bag key (not a typed header property — lives in <see cref="MessageHeader.Bag"/>)
+        /// carrying the publication topic when the message mapper overrides <see cref="MessageHeader.Topic"/>
+        /// (e.g. for Reply messages whose topic is the reply address).
+        /// Read by the outbox dispatcher so it can still locate the registered producer.
         /// </summary>
         public const string ProducerTopicHeaderName = "ProducerTopic";
 

src/Paramore.Brighter/OutboxProducerMediator.cs

@@ -794,6 +794,9 @@ private void Dispatch(IEnumerable<Message> posts, RequestContext requestContext,
                 if (_outBox is null) throw new ArgumentException(NoSyncOutboxError);
                 foreach (var message in posts)
                 {
+                    // Log the wire topic (Header.Topic) — where the message is going. Producer
+                    // lookup uses GetProducerLookupTopic, which may differ from Header.Topic when
+                    // a mapper overrode it (e.g. Reply messages routed to a dynamic reply address).
                     Log.DecoupledInvocationOfMessage(s_logger, message.Header.Topic, message.Id);
 
                     var producer = _producerRegistry.LookupBy(GetProducerLookupTopic(message), message.Header.Type, requestContext);
@@ -854,6 +857,9 @@ private async Task BulkDispatchAsync(
 
                 foreach (var topicBatch in messagesByTopic)
                 {
+                    // Messages in this batch share Header.Topic (the group key). They therefore
+                    // share the same ProducerTopic bag entry (set by WrapPipelineAsync when the
+                    // mapper overrode the topic), so firstMessage is representative of the batch.
                     var firstMessage = topicBatch.First();
                     var producer = _producerRegistry.LookupBy(GetProducerLookupTopic(firstMessage));
                     var span = _tracer?.CreateProducerSpan(producer.Publication, null, requestContext.Span,
@@ -927,6 +933,9 @@ private async Task DispatchAsync(
                 if (_asyncOutbox is null) throw new ArgumentException(NoAsyncOutboxError);
                 foreach (var message in posts)
                 {
+                    // Log the wire topic (Header.Topic) — where the message is going. Producer
+                    // lookup uses GetProducerLookupTopic, which may differ from Header.Topic when
+                    // a mapper overrode it (e.g. Reply messages routed to a dynamic reply address).
                     Log.DecoupledInvocationOfMessage(s_logger, message.Header.Topic, message.Id);
 
                     var producer = _producerRegistry.LookupBy(GetProducerLookupTopic(message), message.Header.Type, requestContext);

src/Paramore.Brighter/WrapPipeline.cs

@@ -94,7 +94,9 @@ public Message Wrap(TRequest request, RequestContext requestContext, Publication
             {
                 Log.DifferentPublicationAndMessageTopic(s_logger, publication.Topic?.Value ?? string.Empty, message.Header.Topic);
                 if (publication.Topic is not null)
+                {
                     message.Header.Bag[Message.ProducerTopicHeaderName] = publication.Topic.Value;
+                }
             }
 
             BrighterTracer.WriteMapperEvent(message, publication, requestContext.Span, MessageMapper.GetType().Name, false, _instrumentationOptions, true);

src/Paramore.Brighter/WrapPipelineAsync.cs

@@ -101,7 +101,9 @@ public async Task<Message> WrapAsync(TRequest request, RequestContext requestCon
             {
                 Log.DifferentPublicationAndMessageTopic(s_logger, publication.Topic?.Value ?? string.Empty, message.Header.Topic);
                 if (publication.Topic is not null)
+                {
                     message.Header.Bag[Message.ProducerTopicHeaderName] = publication.Topic.Value;
+                }
             }
 
             BrighterTracer.WriteMapperEvent(message, publication, requestContext.Span, MessageMapper.GetType().Name, true, _instrumentationOptions, true);

tests/Paramore.Brighter.Core.Tests/CommandProcessors/Post/When_Bulk_Dispatching_Reply_Messages_Async.cs

@@ -97,8 +97,12 @@ await _mediator.ClearOutstandingFromOutboxAsync(
                 useBulk: true,
                 requestContext: context);
 
-            //allow background clear to run
-            await Task.Delay(500);
+            //poll until the background clear drains the outbox (bounded to avoid flake in CI)
+            var deadline = DateTimeOffset.UtcNow + TimeSpan.FromSeconds(5);
+            while (_internalBus.Stream(_replyTopic).Count() < 2 && DateTimeOffset.UtcNow < deadline)
+            {
+                await Task.Delay(25);
+            }
 
             //assert - messages landed on the reply topic. If producer lookup had used
             //Header.Topic (reply address) instead of the bag's ProducerTopic, LookupBy