From d0d59d59f06ed823a159c45b0079703099a7d20f Mon Sep 17 00:00:00 2001
From: Tyler Goodlet <jgbt@protonmail.com>
Date: Wed, 26 Mar 2025 12:55:06 -0400
Subject: [PATCH] First draft `d2` sequence diagrams for `.msg.types`

Documenting nearly all possible `MsgType` flows so they can eventually
be paired with matching code snippets in our (hopefully) soon to be
reworked docs.
---
 docs/dgrams/sc_supervision_dialog_proto.d2 | 124 +++++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 docs/dgrams/sc_supervision_dialog_proto.d2

diff --git a/docs/dgrams/sc_supervision_dialog_proto.d2 b/docs/dgrams/sc_supervision_dialog_proto.d2
new file mode 100644
index 00000000..fb2e182c
--- /dev/null
+++ b/docs/dgrams/sc_supervision_dialog_proto.d2
@@ -0,0 +1,124 @@
+direction: down
+
+vars: {
+  d2-config: {
+    layout-engine: elk
+    # terminal theme code
+
+    # https://d2lang.com/tour/themes
+    # theme-id: 300  # "terminal" they call it ?? XD
+    theme-id: 200  # purple-n-dark?
+    sketch: true
+  }
+}
+
+sc_supervision_protocol_msgspec: 'all `MsgType`s' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    # ------ supervision txns ------
+    # RPC start (aka fn call) of IPC context
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+    # sync parent-child SC tasks
+    child -> parent: 'Started[pld: PayloadT]'
+    # ...
+    # maybe-stream phase
+    # parent -> child: 'Proto[pld: TransportT]'
+    parent <-> child: 'Yield[pld: Any]'
+    # stream termination
+    parent <-> child: "Stop[pld: str]"
+    # ...
+    # termination(s) of IPC context
+    parent -> child: 'Cancel'
+    child -> parent: 'CancelAck'
+    # ... OR
+    child -> parent: 'Error[pld: TracebackType]'
+    # ... OR
+    child -> parent: 'Return[pld: PayloadT]'
+}
+
+
+std_rpc: 'classic fn call with final result' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+    child -> parent: 'Started[pld: PayloadT]'
+    child -> parent: 'Return[pld: PayloadT]'
+}
+
+
+std_rpc_w_streaming: 'fn call, streaming phase, then final result' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+    child -> parent: 'Started[pld: PayloadT]'
+    parent <-> child: 'Yield[pld: Any]'
+    parent <-> child: "Stop[pld: str]"
+    child -> parent: 'Return[pld: PayloadT]'
+}
+
+
+rpc_w_chld_err: 'child errors mid streaming-phase' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+    child -> parent: 'Started[pld: PayloadT]'
+    parent <-> child: 'Yield[pld: PayloadT]'
+    child -> parent: 'Error[pld: TracebackType]'
+}
+
+
+rpc_w_rent_err_before_started: 'parent errors then cancels child before `Context.started()`' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+    parent -> child: 'Cancel'
+    child -> parent: 'CancelAck'
+}
+
+
+graceful_ctxc_rent_to_child: 'parent cancels child mid stream' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+    child -> parent: 'Started[pld: PayloadT]'
+    parent <-> child: 'Yield[pld: PayloadT]'
+    parent -> child: 'Cancel'
+    child -> parent: 'CancelAck'
+}
+
+graceful_ctxc_child: 'child self-cancels before started' {
+    shape: sequence_diagram
+
+    parent: 'parent: Task'
+    child: 'child: Task'
+
+    parent -> child: 'Start[CallSpec]'
+    child -> parent: 'StartAck[CallSpec]'
+
+    child -> parent: 'Cancel'
+    parent -> child: 'CancelAck'
+}