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'
+}