Clarify pointer and IPC cancellation contracts

Source prose left the stalled transport peer ambiguous, omitted why a
local namespace pointer retains its object and described cancellation
as interrupting a frame write which is now shielded.

Identify remote-peer and bounded-cancel behavior, document process-local
pointer caching, and explain the shield completion checkpoint which
makes startup cancellation protocol-safe on a connected channel.

Review: PR #481 (goodboy)
https://github.com/goodboy/tractor/pull/481#pullrequestreview-5012942328

(this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`))

tractor/ipc/_transport.py

@@ -518,9 +518,10 @@ class MsgpackTransport(MsgTransport):
                 # the frame is complete, the explicit checkpoint
                 # immediately delivers any pending cancellation.
                 #
-                # Ordinary sends may delay cancellation while a peer is
-                # not reading. Actor-wide cancel requests pass their own
-                # deadline so this operation can close a stalled stream.
+                # Ordinary sends may delay cancellation while the remote
+                # peer actor is not reading. Bounded actor/context cancel
+                # requests pass an absolute deadline so this operation
+                # can close a stalled stream.
                 with trio.CancelScope(
                     deadline=send_deadline,
                     shield=True,

tractor/msg/ptr.py

@@ -123,6 +123,15 @@ class NamespacePath(str):
         ref: type|object,
 
     ) -> NamespacePath:
+        '''
+        Build a path while retaining its process-local object reference.
+
+        The originating process already holds `ref`; caching it prevents
+        `to_tuple()` from immediately importing and resolving the same
+        object again. Serialized paths carry only the `str` value and
+        therefore resolve lazily through `load_ref()` after decoding.
+
+        '''
 
         fqnp: tuple[str, str] = cls._mk_fqnp(ref)
         nsp = cls(':'.join(fqnp))

tractor/runtime/_runtime.py

@@ -882,12 +882,15 @@ class Actor:
 
         except BaseException as startup_err:
             with trio.CancelScope(shield=True):
-                # `MsgpackTransport.send()` closes its stream when
-                # cancellation interrupts the length-prefixed write
-                # because an unknown prefix may already be sent. A
-                # connected channel means cancellation happened before
-                # that write or after it completed, so `_cancel_task`
-                # is protocol-safe (and a no-op if `Start` was unsent).
+                # `MsgpackTransport.send()` shields length-prefixed frame
+                # publication until complete, then checkpoints pending
+                # cancellation before returning. Thus `start_published`
+                # can remain false after a complete `Start` reached the
+                # wire. If the send's own deadline catches a partial
+                # frame, it closes the stream. A connected channel means
+                # cancellation happened before the write or after frame
+                # completion, so `_cancel_task` is protocol-safe (and
+                # a no-op when `Start` was unsent).
                 if (
                     cancel_on_startup
                     and