=doc document why Deliver takes an ActorPath

akka-docs/rst/java/persistence.rst

@@ -240,6 +240,24 @@ request  instructs a channel to send a ``Persistent`` message to a destination.
 ``ActorPath`` and messages are sent by the channel via that path's ``ActorSelection``. Sender references are
 preserved by a channel, therefore, a destination can reply to the sender of a ``Deliver`` request.
 
+.. note::
+  
+  Sending via a channel has at-least-once delivery semantics—by virtue of either
+  the sending actor or the channel being persistent—which means that the
+  semantics do not match those of a normal :class:`ActorRef` send operation:
+
+  * it is not at-most-once delivery
+
+  * message order for the same sender–receiver pair is not retained due to
+    possible resends
+
+  * after a crash and restart of the destination messages are still
+    delivered—to the new actor incarnation
+
+  These semantics match precisely what an :class:`ActorPath` represents (see
+  :ref:`actor-lifecycle-java`), therefore you need to supply a path and not a
+  reference when constructing :class:`Deliver` messages.
+
 If a processor wants to reply to a ``Persistent`` message sender it should use the ``getSender()`` path as
 channel destination.
 

akka-docs/rst/java/untyped-actors.rst

@@ -217,6 +217,8 @@ described in the following:
 The implementations shown above are the defaults provided by the :class:`UntypedActor`
 class.
 
+.. _actor-lifecycle-java:
+
 Actor Lifecycle
 ---------------
 

akka-docs/rst/project/migration-guide-eventsourced-2.3.x.rst

@@ -27,7 +27,7 @@ Eventsourced and Akka Persistence are both :ref:`extending-akka-scala`.
 **Eventsourced:** ``EventsourcingExtension``
 
 - Must be explicitly created with an actor system and an application-defined journal actor as arguments.
-  (see `usage example <https://github.com/eligosource/eventsourced#step-1-eventsourcingextension-initialization>`_).
+  (see `example usage <https://github.com/eligosource/eventsourced#step-1-eventsourcingextension-initialization>`_).
 - `Processors <https://github.com/eligosource/eventsourced#processor>`_ and
   `Channels <https://github.com/eligosource/eventsourced#channel>`_
   must be created with the factory methods ``processorOf`` and ``channelOf`` defined on ``EventsourcingExtension``.

akka-docs/rst/scala/actors.rst

@@ -255,6 +255,8 @@ described in the following:
 The implementations shown above are the defaults provided by the :class:`Actor`
 trait.
 
+.. _actor-lifecycle-scala:
+
 Actor Lifecycle
 ---------------
 

akka-docs/rst/scala/persistence.rst

@@ -237,6 +237,24 @@ request  instructs a channel to send a ``Persistent`` message to a destination.
 ``ActorPath`` and messages are sent by the channel via that path's ``ActorSelection``. Sender references are
 preserved by a channel, therefore, a destination can reply to the sender of a ``Deliver`` request.
 
+.. note::
+  
+  Sending via a channel has at-least-once delivery semantics—by virtue of either
+  the sending actor or the channel being persistent—which means that the
+  semantics do not match those of a normal :class:`ActorRef` send operation:
+
+  * it is not at-most-once delivery
+
+  * message order for the same sender–receiver pair is not retained due to
+    possible resends
+
+  * after a crash and restart of the destination messages are still
+    delivered—to the new actor incarnation
+
+  These semantics match precisely what an :class:`ActorPath` represents (see
+  :ref:`actor-lifecycle-scala`), therefore you need to supply a path and not a
+  reference when constructing :class:`Deliver` messages.
+
 If a processor wants to reply to a ``Persistent`` message sender it should use the ``sender`` path as channel
 destination.