From bf15ee731ab6ee4dad4998f91f11c808dce14f48 Mon Sep 17 00:00:00 2001
From: Sergei Predvoditelev <sergei@predvoditelev.ru>
Date: Wed, 6 May 2026 11:33:07 +0300
Subject: [PATCH] Narrow message metadata type to `array<string, mixed>`

---
 src/Message/Envelope.php         | 3 +++
 src/Message/IdEnvelope.php       | 4 +---
 src/Message/Message.php          | 2 ++
 src/Message/MessageInterface.php | 4 +++-
 src/Queue.php                    | 1 -
 5 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/src/Message/Envelope.php b/src/Message/Envelope.php
index 6599feb6..800ebae2 100644
--- a/src/Message/Envelope.php
+++ b/src/Message/Envelope.php
@@ -8,6 +8,9 @@
 
 abstract class Envelope implements EnvelopeInterface
 {
+    /**
+     * @psalm-var array<string, mixed>|null
+     */
     private ?array $metadata = null;
 
     public function __construct(protected MessageInterface $message) {}
diff --git a/src/Message/IdEnvelope.php b/src/Message/IdEnvelope.php
index 0fb00e9d..891f9883 100644
--- a/src/Message/IdEnvelope.php
+++ b/src/Message/IdEnvelope.php
@@ -22,13 +22,11 @@ public function __construct(
 
     public static function fromMessage(MessageInterface $message): static
     {
-        /** @var mixed $rawId */
         $rawId = $message->getMetadata()[self::MESSAGE_ID_KEY] ?? null;
 
-        /** @var int|string|null $id */
         $id = match (true) {
             $rawId === null => null, // don't remove this branch: it's important for compute speed
-            is_string($rawId) => $rawId,
+            is_string($rawId),
             is_int($rawId) => $rawId,
             is_object($rawId) && method_exists($rawId, '__toString') => (string) $rawId,
             default => null,
diff --git a/src/Message/Message.php b/src/Message/Message.php
index e07dc09f..ff4d34f4 100644
--- a/src/Message/Message.php
+++ b/src/Message/Message.php
@@ -10,6 +10,8 @@ final class Message implements MessageInterface
      * @param string $type A message type used to resolve the handler.
      * @param mixed $data Message data, encodable by a queue adapter
      * @param array $metadata Message metadata, encodable by a queue adapter
+     *
+     * @psalm-param array<string, mixed> $metadata
      */
     public function __construct(
         private readonly string $type,
diff --git a/src/Message/MessageInterface.php b/src/Message/MessageInterface.php
index 404e3eea..4254eebb 100644
--- a/src/Message/MessageInterface.php
+++ b/src/Message/MessageInterface.php
@@ -19,7 +19,9 @@ public function getType(): string;
     public function getData(): mixed;
 
     /**
-     * Returns message metadata: timings, attempts count, metrics, etc.
+     * Returns message metadata: timings, attempts count, metrics, etc. Keys are always strings.
+     *
+     * @return array<string, mixed>
      */
     public function getMetadata(): array;
 }
diff --git a/src/Queue.php b/src/Queue.php
index 73ae0a63..8c303582 100644
--- a/src/Queue.php
+++ b/src/Queue.php
@@ -96,7 +96,6 @@ public function push(MessageInterface $message): MessageInterface
             return $message;
         }
 
-        /** @var string $messageId */
         $messageId = $message->getMetadata()[IdEnvelope::MESSAGE_ID_KEY] ?? 'null';
         $this->logger->info(
             'Pushed message with message type "{messageType}" to the queue. Assigned ID #{id}.',