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