docs: clarify auto-variadic socket input ordering in connect()

Document the input ordering behavior of auto-promoted lazy variadic
sockets in Pipeline.connect() and PipelineBase._make_socket_auto_variadic().
When multiple senders are connected to the same list-typed receiver
socket, the items in the resulting list are ordered alphabetically by
sender component name (because Pipeline.run() schedules components in
alphabetical order for deterministic execution), not by the order in
which connect() was called.

The docstrings now point users to a dedicated joiner component when
they need explicit ordering.

fixes #10979

Author: saivedant169

haystack/core/pipeline/base.py

@@ -446,6 +446,13 @@ def connect(self, sender: str, receiver: str) -> "PipelineBase":  # noqa: PLR091
         If connecting to a component that has several output connections, specify the inputs and output names as
         'component_name.connections_name'.
 
+        When multiple senders are connected to the same list-typed receiver socket, the socket is
+        automatically promoted to a lazy-variadic socket so it can accept all of them. The items
+        in the resulting list are ordered by sender component name (alphabetically), not by the
+        order in which ``connect()`` was called. If your downstream component depends on a specific
+        input order, use a dedicated joiner component (for example ``DocumentJoiner``) that lets
+        you control ordering explicitly.
+
         :param sender:
             The component that delivers the value. This can be either just a component name or can be
             in the format `component_name.connection_name` if the component has multiple outputs.
@@ -956,6 +963,15 @@ def _make_socket_auto_variadic(
         When auto-variadicity is applied, `wrap_input_in_list` is also set to False so that sender output types match
         the receiver socket's declared list type directly.
 
+        .. note::
+            When multiple senders are connected to the same auto-variadic socket, the items
+            in the resulting list are ordered by sender component name (alphabetically), not by
+            the order in which the connections were declared via ``connect()``. This is because
+            ``Pipeline.run()`` schedules components in alphabetical order so that execution is
+            deterministic and independent of pipeline insertion order. If your downstream
+            component is sensitive to the input order, consider using a dedicated joiner
+            component that lets you control ordering explicitly.
+
         :param component_name:
             Name of the component owning the receiver socket, used in error messages.
         :param receiver_socket:

releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml

@@ -0,0 +1,10 @@
+---
+enhancements:
+  - |
+    Document the input ordering behavior of auto-promoted lazy variadic sockets in
+    ``Pipeline.connect()`` and ``PipelineBase._make_socket_auto_variadic()``. When
+    multiple senders are connected to the same list-typed receiver socket, the items
+    in the resulting list are ordered alphabetically by sender component name (because
+    ``Pipeline.run()`` schedules components in alphabetical order for deterministic
+    execution), not by the order in which ``connect()`` was called. The docstrings now
+    point users to a dedicated joiner component when they need explicit ordering.