Clarify the semantics for variable assignment

[QuantumGhost]

Semantics for VariableAssigner in current implementation

Currently, VariableAssigner v1 and v2 are the only nodes allowed to mutate variables during workflow execution.

However, the implementation of the two nodes currently does not restrict which variables could be mutated. The only restriction comes from the workflow orchestration UI.

More specifically, the frontend UI limit the assignment targets to conversation variables for top-level VariableAssigner nodes:

For VariableAssigner nodes inside Loop / Iteration nodes, the loop index variable, iteration index variable and iteration value variable are also assignable:

Since graphon has been extracted as a library, the frontend limitation does not apply anymore. The semantics of the VariableAssigner node needs to be clarified. If the limit still applies to VariableAssigner node, I believe we should implement this limit in code, instead of allowing the users of graphon to assign to variables which are considered immutable.

DSL for the example above

app:
  description: ''
  icon: 🤖
  icon_background: '#FFEAD5'
  icon_type: emoji
  mode: advanced-chat
  name: AssignerSemantics
  use_icon_as_answer_icon: false
dependencies: []
kind: app
version: 0.6.0
workflow:
  conversation_variables:
  - description: test
    id: e39ede7e-e784-4498-9bfb-66e4a9bf8fb3
    name: conv_var
    selector:
    - conversation
    - conv_var
    value: test
    value_type: string
  environment_variables: []
  features:
    file_upload:
      allowed_file_extensions:
      - .JPG
      - .JPEG
      - .PNG
      - .GIF
      - .WEBP
      - .SVG
      allowed_file_types:
      - image
      allowed_file_upload_methods:
      - local_file
      - remote_url
      enabled: false
      fileUploadConfig:
        attachment_image_file_size_limit: 2
        audio_file_size_limit: 50
        batch_count_limit: 5
        file_size_limit: 15
        file_upload_limit: 50
        image_file_batch_limit: 10
        image_file_size_limit: 10
        single_chunk_attachment_limit: 10
        video_file_size_limit: 100
        workflow_file_upload_limit: 10
      image:
        enabled: false
        number_limits: 3
        transfer_methods:
        - local_file
        - remote_url
      number_limits: 3
    opening_statement: ''
    retriever_resource:
      enabled: true
    sensitive_word_avoidance:
      enabled: false
    speech_to_text:
      enabled: false
    suggested_questions: []
    suggested_questions_after_answer:
      enabled: false
    text_to_speech:
      enabled: false
      language: ''
      voice: ''
  graph:
    edges:
    - data:
        isInIteration: false
        isInLoop: false
        sourceType: assigner
        targetType: loop
      id: 1775718594480-source-1775718589443-target
      source: '1775718594480'
      sourceHandle: source
      target: '1775718589443'
      targetHandle: target
      type: custom
      zIndex: 0
    - data:
        isInIteration: false
        isInLoop: false
        sourceType: assigner
        targetType: iteration
      id: 1775718594480-source-1775718633046-target
      source: '1775718594480'
      sourceHandle: source
      target: '1775718633046'
      targetHandle: target
      type: custom
      zIndex: 0
    - data:
        isInIteration: true
        isInLoop: false
        iteration_id: '1775718633046'
        sourceType: iteration-start
        targetType: assigner
      id: 1775718633046start-source-1775718642679-target
      source: 1775718633046start
      sourceHandle: source
      target: '1775718642679'
      targetHandle: target
      type: custom
      zIndex: 1002
    - data:
        isInIteration: false
        isInLoop: false
        sourceType: loop
        targetType: answer
      id: 1775718589443-source-1775718657295-target
      source: '1775718589443'
      sourceHandle: source
      target: '1775718657295'
      targetHandle: target
      type: custom
      zIndex: 0
    - data:
        isInLoop: false
        sourceType: iteration
        targetType: answer
      id: 1775718633046-source-1775718657295-target
      source: '1775718633046'
      sourceHandle: source
      target: '1775718657295'
      targetHandle: target
      type: custom
      zIndex: 0
    - data:
        isInIteration: false
        isInLoop: true
        loop_id: '1775718589443'
        sourceType: loop-start
        targetType: assigner
      id: 1775718589443start-source-1775718669662-target
      source: 1775718589443start
      sourceHandle: source
      target: '1775718669662'
      targetHandle: target
      type: custom
      zIndex: 1002
    - data:
        isInIteration: false
        isInLoop: false
        sourceType: start
        targetType: code
      id: 1775707133096-source-1775719093003-target
      source: '1775707133096'
      sourceHandle: source
      target: '1775719093003'
      targetHandle: target
      type: custom
      zIndex: 0
    - data:
        isInIteration: false
        isInLoop: false
        sourceType: code
        targetType: assigner
      id: 1775719093003-source-1775718594480-target
      source: '1775719093003'
      sourceHandle: source
      target: '1775718594480'
      targetHandle: target
      type: custom
      zIndex: 0
    - data:
        isInIteration: true
        isInLoop: false
        iteration_id: '1775718633046'
        sourceType: assigner
        targetType: template-transform
      id: 1775718642679-source-1775719151996-target
      source: '1775718642679'
      sourceHandle: source
      target: '1775719151996'
      targetHandle: target
      type: custom
      zIndex: 1002
    nodes:
    - data:
        selected: false
        title: User Input
        type: start
        variables: []
      height: 73
      id: '1775707133096'
      position:
        x: 0
        y: 79
      positionAbsolute:
        x: 0
        y: 79
      sourcePosition: right
      targetPosition: left
      type: custom
      width: 242
    - data:
        break_conditions:
        - comparison_operator: <
          id: 2d7dfa2c-bd6a-4c12-b907-ff509e6bb1d5
          value: '10'
          varType: number
          variable_selector:
          - '1775718589443'
          - index
        error_handle_mode: terminated
        height: 204
        logical_operator: and
        loop_count: 10
        loop_variables:
        - id: 4b32f071-42e8-4b7b-88a5-748cb2f3c60a
          label: index
          value: '0'
          value_type: constant
          var_type: number
        selected: false
        start_node_id: 1775718589443start
        title: Loop
        type: loop
        width: 486
      height: 204
      id: '1775718589443'
      position:
        x: 1046
        y: 0
      positionAbsolute:
        x: 1046
        y: 0
      selected: false
      sourcePosition: right
      targetPosition: left
      type: custom
      width: 486
      zIndex: 1
    - data:
        desc: ''
        isInLoop: true
        selected: false
        title: ''
        type: loop-start
      draggable: false
      height: 48
      id: 1775718589443start
      parentId: '1775718589443'
      position:
        x: 60
        y: 78
      positionAbsolute:
        x: 1106
        y: 78
      selectable: false
      sourcePosition: right
      targetPosition: left
      type: custom-loop-start
      width: 44
      zIndex: 1002
    - data:
        items:
        - input_type: constant
          operation: set
          value: '1'
          variable_selector:
          - conversation
          - conv_var
          write_mode: over-write
        selected: false
        title: Variable Assigner
        type: assigner
        version: '2'
      height: 84
      id: '1775718594480'
      position:
        x: 684
        y: 74
      positionAbsolute:
        x: 684
        y: 74
      selected: false
      sourcePosition: right
      targetPosition: left
      type: custom
      width: 242
    - data:
        error_handle_mode: terminated
        flatten_output: true
        height: 230
        is_parallel: false
        iterator_input_type: array[string]
        iterator_selector:
        - '1775719093003'
        - strings
        output_selector:
        - '1775719151996'
        - output
        output_type: array[string]
        parallel_nums: 10
        selected: false
        start_node_id: 1775718633046start
        title: Iteration
        type: iteration
        width: 808
      height: 230
      id: '1775718633046'
      position:
        x: 1046
        y: 284
      positionAbsolute:
        x: 1046
        y: 284
      selected: false
      sourcePosition: right
      targetPosition: left
      type: custom
      width: 808
      zIndex: 1
    - data:
        desc: ''
        isInIteration: true
        selected: false
        title: ''
        type: iteration-start
      draggable: false
      height: 48
      id: 1775718633046start
      parentId: '1775718633046'
      position:
        x: 60
        y: 91
      positionAbsolute:
        x: 1106
        y: 375
      selectable: false
      sourcePosition: right
      targetPosition: left
      type: custom-iteration-start
      width: 44
      zIndex: 1002
    - data:
        isInIteration: true
        isInLoop: false
        items:
        - input_type: constant
          operation: set
          value: 0
          variable_selector:
          - '1775718633046'
          - index
          write_mode: over-write
        - input_type: variable
          operation: over-write
          value:
          - sys
          - query
          variable_selector:
          - '1775718633046'
          - item
          write_mode: over-write
        iteration_id: '1775718633046'
        selected: true
        title: Iter Var Assigner
        type: assigner
        version: '2'
      height: 110
      id: '1775718642679'
      parentId: '1775718633046'
      position:
        x: 184
        y: 60
      positionAbsolute:
        x: 1230
        y: 344
      selected: true
      sourcePosition: right
      targetPosition: left
      type: custom
      width: 242
      zIndex: 1002
    - data:
        answer: '0'
        selected: false
        title: Answer
        type: answer
        variables: []
      height: 100
      id: '1775718657295'
      position:
        x: 1974
        y: 69
      positionAbsolute:
        x: 1974
        y: 69
      selected: false
      sourcePosition: right
      targetPosition: left
      type: custom
      width: 242
    - data:
        isInIteration: false
        isInLoop: true
        items:
        - input_type: constant
          operation: set
          value: 0
          variable_selector:
          - '1775718589443'
          - index
          write_mode: over-write
        loop_id: '1775718589443'
        selected: false
        title: Loop Var Assigner
        type: assigner
        version: '2'
      height: 84
      id: '1775718669662'
      parentId: '1775718589443'
      position:
        x: 184
        y: 60
      positionAbsolute:
        x: 1230
        y: 60
      selected: false
      sourcePosition: right
      targetPosition: left
      type: custom
      width: 242
      zIndex: 1002
    - data:
        code: "\ndef main():\n    return {\n        \"strings\": [],\n    }\n"
        code_language: python3
        outputs:
          strings:
            children: null
            type: array[string]
        selected: false
        title: VariableCreator
        type: code
        variables: []
      height: 52
      id: '1775719093003'
      position:
        x: 342
        y: 90
      positionAbsolute:
        x: 342
        y: 90
      sourcePosition: right
      targetPosition: left
      type: custom
      width: 242
    - data:
        isInIteration: true
        isInLoop: false
        iteration_id: '1775718633046'
        selected: false
        template: '0'
        title: Template
        type: template-transform
        variables: []
      height: 52
      id: '1775719151996'
      parentId: '1775718633046'
      position:
        x: 506
        y: 89
      positionAbsolute:
        x: 1552
        y: 373
      sourcePosition: right
      targetPosition: left
      type: custom
      width: 242
      zIndex: 1002
    viewport:
      x: 211
      y: 216
      zoom: 0.7
  rag_pipeline_variables: []

[laipz8200]

Currently, we have no reason to impose restrictions on this assignment behavior.

In my view, we only need to ensure that the action of modifying variables is performed by the engine rather than the nodes.

[QuantumGhost]

@laipz8200 The current implementation of GraphEngine uses a flat scope for variables, where variables are scoped by their node_id. Container nodes, such as Loop, Iteration, or WorkflowTool, utilize a child GraphEngine for execution, which also serves as an isolation boundary. Consequently, allowing arbitrary variable assignment is relatively simple in the current architecture.

However, variable assignment semantics for nested containers become significantly more complex if we remove child engines without imposing a robust variable isolation mechanism.

Consider a scenario where a workflow contains a variable_assigner inside an iteration node:

In this case, the iteration node collects the output of the http_request node from each round into an array as its final output. This raises several semantic questions that need to be addressed:

• Should we allow a variable_assigner inside the iteration to update the outputs of the code node (which is outside or at a different level)?
• Should we allow the variable_assigner to set a variable for a node (e.g., template) that has not yet been executed?
• Should the variable_assigner be allowed to modify the iteration node's own variables?
  • If yes, how does this assignment affect GraphEngine components that depend on those node outputs?
• If we allow the variable_assigner to mutate the output of the http_request node, should this modification be reflected in the final collected array?

These semantic ambiguities multiply with nested loops or iterations. For example, in the graph below:

• Should the variable_assigner be allowed to modify the loop variable i? If the loop condition depends on i, how should this assignment affect the execution flow?

The core issue here is not just finding specific answers, but defining a formal specification. In my view, the entire graphon is essentially a visual programming language: the GraphEngine acts as the interpreter, and the graphs are the source code. Currently, we lack a formal specification for this language. Past behavior has been largely "implementation-defined," which was manageable when users were constrained by the frontend. However, now that graphon is being extracted as a framework, developers have an infinite number of ways to construct graphs. Without a clear specification, we cannot definitively answer why a specific graph fails to behave as expected.

We don't need a complete specification immediately, but we should aim to build it incrementally. I suggest we involve @asukaminato0721 in these discussions, given his solid background in Programming Language (PL) theory.

Additionally, I suggest adding the ADR documentation for those specification decisions so we could check and reference them later.

[asukaminato0721]

Should we allow a variable_assigner inside the iteration to update the outputs of the code node (which is outside or at a different level)?

Depend whether there are concurrency functions.

pseudocode

x = 1
go func() {
   x = 2
}
go func() {
   x = 3
}
x = ?

So we should either introduce lock, or don't allow it.

in rust we have ownership. But will it be hard to maintain?

[asukaminato0721]

Should the variable_assigner be allowed to modify the loop variable i? If the loop condition depends on i, how should this assignment affect the execution flow?

In other lang like Lua 5.4, you cannot change the loop variable (often denoted as i or k) inside a for loop, as it is considered local and its modification leads to undefined behavior or errors.

So I think it should be readonly.

since in normal way, either

for i = 0; i < xx ; i ++ {
}

this is enum index based loop

while pred 
    i ++

this is "guard" based loop

mix 1 and 2 is ... very strange imo.

[asukaminato0721]

Should we allow the variable_assigner to set a variable for a node (e.g., template) that has not yet been executed?

again the "race".

go func() {
   set template = 1
}
go func() {
   set template = 2
}

use template here

[QuantumGhost]

@asukaminato0721 Thanks for pointing out the concurrency scenario.

To clarify the current implementation:

1. Loop is similar to a traditional for loop. It does not support parallel execution.
2. Iteration is similar to a functional map. It supports both sequential execution and a parallel mode, which is roughly equivalent to parallel_map.
3. Variables are managed by VariablePool, which uses a two-level namespace:
   • node_id: the identifier of the node that outputs the variable
   • variable_name: the name of the variable
4. Both Loop and Iteration execute their subgraphs through child graph engines.
   • For Loop, execution is sequential.
   • For Iteration in sequential mode, each round runs with a child engine derived from the parent execution context.
   • For Iteration in parallel mode, each round runs in its own child engine with its own copied VariablePool, and the parent engine later collects the outputs and forwards the resulting events.

With that in mind, the current implementation allows VariableAssigner to update:

• conversation variables, regardless of where the VariableAssigner is placed
• loop / iteration variables introduced by its direct parent Loop or Iteration

What is not well defined is whether VariableAssigner should also be allowed to update output variables produced by other nodes.
Historically, the workflow UI prevented users from constructing such DSLs, but now that graphon is a library, those orchestration-layer restrictions no longer exist.

So the main semantic questions are:

1. Should VariableAssigner be allowed to write to output variables owned by other nodes?
2. Inside a Loop or Iteration, should VariableAssigner be allowed to write to any variables other than conversation variables and the loop / iteration variables introduced by its direct parent?

My view is that we should make this stricter in code. Concretely, I would suggest that VariableAssigner should only be allowed to write to:

• conversation variables
• loop / iteration variables introduced by its direct parent container

In other words, it should not be able to mutate arbitrary output variables from other nodes, nor loop variables coming from non-direct or outer containers.

But @laipz8200 has a different view and suggests that graphon should remain more permissive and leave this unrestricted for library users.

[laipz8200]

Should we introduce a mechanism for creating variables that explicitly distinguishes them from other read-only variables?

The downstream could then utilize this specific class of variables to implement features such as Conversation Variables.

[QuantumGhost]

Should we introduce a mechanism for creating variables that explicitly distinguishes them from other read-only variables?

The downstream could then utilize this specific class of variables to implement features such as Conversation Variables.

I agree with this direction. My initial thought was to introduce a readonly flag to the Variable class, enabling downstream systems to set it appropriately and ensure conversation variables remain assignable.

After examining the current UI restrictions, I found that the only variables allowed to persist across scope boundaries are those introduced by Loop nodes. These remain assignable even outside the loop (as shown in the image below). This suggests that, for now, we do not need to bind the readonly flag to a specific scope.

The readonly / writable flag seems a perfect fit for the current implementation.

That said, if we consider subgraph expansion in the future, variable mutability should ideally be scope-bound. I suggest we defer the discussion of subgraph expansion semantics to a separate issue.