Frontend-Backend Action Mapping: Workflow Editor Undo/Redo Persistence

1. Frontend Action Inventory

Base Classes

Step Actions (Actions/stepActions.ts)

Workflow Actions (Actions/workflowActions.ts)

Comment Actions (Actions/commentActions.ts)

Connection Actions (via FactoryAction in modules/terminals.ts)

SetValueActionHandler Instances (Index.vue)

2. Backend Refactor Action Inventory

Action Classes (refactor/schema.py)

Step Reference Types (schema.py:25-57)

No StepReferenceById exists yet. Frontend uses numeric step IDs; backend only supports order_index and label.

Position Model (schema.py:60-69)

class Position(BaseModel):
    left: float
    top: float

Only supports relative shift currently. No absolute positioning.

Request Model (schema.py:267-269)

class RefactorActions(BaseModel):
    actions: list[union_action_classes]
    dry_run: bool = False

No title or source_action_type fields yet.

Step Resolution (execute.py:419-435)

_find_step does:

1. StepReferenceByLabel → linear scan of steps matching label
2. Else assumes StepReferenceByOrderIndex → direct dict lookup
3. Validates order_index < len(steps)

Problem: The else branch assumes anything non-label is order_index. Adding StepReferenceById requires explicit isinstance checks.

3. Frontend → Backend Action Mapping

Direct Mappings (Ready to Serialize)

Needs Backend Enhancement

Needs New Backend Actions (Comments)

No Backend Equivalent Needed (UI-Only)

4. RemoveStepAction Specification

Frontend Behavior (stepActions.ts:322-362)

On run:

1. stepStore.removeStep(stepId) which:
   • Removes all connections for step (both incoming/outgoing) via connectionStore
   • Deletes step from steps dict
   • Cleans up extra inputs, multi-select state, mapOver state, positions, terminals
2. Sets activeNodeId = null
3. Marks hasChanges = true

On undo:

1. stepStore.addStep(step) — restores cloned step
2. Re-adds all saved connections via connectionStore.addConnection()
3. Marks hasChanges = true

Backend Requirements

class RemoveStepAction(BaseAction):
    action_type: Literal["remove_step"]
    step: step_reference_union = step_target_field

Executor _apply_remove_step must:

1. Resolve step reference via _find_step()
2. Get step’s order_index
3. Find all connections where this step is referenced:
   • As output: scan all steps’ input_connections for entries where connection["id"] == removed_step["id"]
   • As input: remove input_connections from the step itself
4. For each dropped connection → emit connection_drop_forced message
5. For each workflow_output on removed step → emit workflow_output_drop_forced message
6. Remove step from self._as_dict["steps"]
7. Tolerate order_index gaps — do NOT re-index remaining steps

Connection Cleanup Algorithm

removed_step_id = step["id"]
for other_order_index, other_step in self._as_dict["steps"].items():
    if other_order_index == order_index:
        continue
    input_connections = other_step.get("input_connections", {})
    for input_name, connections in input_connections.items():
        connections = _listify_connections(connections)
        for conn in connections:
            if conn["id"] == removed_step_id:
                # emit connection_drop_forced message
        input_connections[input_name] = [c for c in connections if c["id"] != removed_step_id]

5. Position Handling Strategy

Current State

• Backend UpdateStepPositionAction only supports position_shift (relative delta)
• Frontend stores/operates on absolute positions ({left, top})

Required Changes

class UpdateStepPositionAction(BaseAction):
    action_type: Literal["update_step_position"]
    step: step_reference_union = step_target_field
    position_shift: Optional[Position] = None
    position_absolute: Optional[Position] = None

    @model_validator(mode='after')
    def validate_position_exactly_one(self):
        if self.position_shift is None and self.position_absolute is None:
            raise ValueError("Must provide either position_shift or position_absolute")
        if self.position_shift is not None and self.position_absolute is not None:
            raise ValueError("Cannot provide both position_shift and position_absolute")
        return self

Executor change:

def _apply_update_step_position(self, action, execution):
    step = self._find_step_for_action(action)
    if action.position_absolute:
        step["position"] = action.position_absolute.to_dict()
    elif action.position_shift:
        # existing relative logic
        step["position"]["left"] += action.position_shift.left
        step["position"]["top"] += action.position_shift.top

Serialization Strategy

• Frontend always serializes with position_absolute (simpler, no delta calc needed)
• position_shift retained for backward compat with existing callers

6. Step Reference Strategy

Current State

• Backend supports: StepReferenceByOrderIndex, StepReferenceByLabel
• Frontend references steps by numeric id (database PK)
• Connection storage uses step "id" field (which equals order_index in workflow dict)

ID Semantics

Required Changes

class StepReferenceById(BaseModel):
    id: int  # Database PK of WorkflowStep

class InputReferenceById(StepReferenceById):
    input_name: str

class OutputReferenceById(StepReferenceById):
    output_name: Optional[str] = output_name_field

Update unions:

step_reference_union = Union[StepReferenceByOrderIndex, StepReferenceByLabel, StepReferenceById]
input_reference_union = Union[InputReferenceByOrderIndex, InputReferenceByLabel, InputReferenceById]
output_reference_union = Union[OutputReferenceByOrderIndex, OutputReferenceByLabel, OutputReferenceById]

Update _find_step to use explicit isinstance checks for all three types instead of the current if/else that assumes non-label = order_index.

Open Question

The frontend’s Step.id is loaded from step_dict["id"] which is order_index. The database WorkflowStep.id (auto-increment PK) is a different value. Which “id” should StepReferenceById use? The plan says database PK, but the frontend doesn’t currently have access to it during editing. Resolution needed.

7. Comment Persistence

Storage Architecture

Database model (model/__init__.py:9188-9269):

• Table: workflow_comment
• id (PK, auto-increment) — internal, not exposed
• order_index — stable identifier exposed as "id" in JSON
• workflow_id (FK to Workflow)
• type (“text”, “markdown”, “frame”, “freehand”)
• position (MutableJSONType) — [x, y]
• size (JSONType) — [width, height]
• color (String(16))
• data (JSONType) — type-specific content
• parent_comment_id (FK, self-referential) — frame nesting

Pydantic schema (schema/workflow/comments.py):

• BaseComment: id, color, position, size
• TextComment: data = {bold?, italic?, size, text}
• MarkdownComment: data = {text}
• FrameComment: data = {title}, child_comments?, child_steps?
• FreehandComment: data = {thickness, line: [[x,y]…]}

ID Management

• Frontend assigns: highestCommentId + 1 (commentStore)
• Backend stores: order_index (mapped as “id” in JSON)
• IDs are stable across saves — preserved in export/import
• Deletion does NOT renumber remaining comment IDs
• FrameComment.child_comments references other comments by this stable ID

Export/Import

• Exported in _workflow_to_dict_editor() and _workflow_to_dict_instance() as [comment.to_dict() for comment in workflow.comments]
• Imported via WorkflowComment.from_dict(dict) which maps dict["id"] → order_index
• Parent-child relationships restored during import (L900-909 of workflows.py)

Position/Size Format Difference

Comment actions use tuples, NOT Position model’s {left, top} dict. The executor must handle this format.

New Size Model Needed

class Size(BaseModel):
    width: float
    height: float

    def to_dict(self):
        return {"width": self.width, "height": self.height}

Do NOT reuse Position — left/top fields are misleading for width/height. Note: comment size in workflow JSON is [width, height] tuple, not {width, height} dict. Executor converts between formats.

8. Connection Handling

Architecture

• Frontend: Connections are separate entities in workflowConnectionStore, synced bidirectionally to step.input_connections
• Backend: Connections are properties of input steps (step["input_connections"][input_name])
• Backend actions exist: ConnectAction and DisconnectAction are fully implemented

Frontend Connection Flow

Terminal.connect(other)
  → FactoryAction("connect steps")
    → onRun: connectionStore.addConnection(connection)
      → stepStore.addConnection(connection)  // sync to input_connections
    → onUndo: connectionStore.removeConnection(connectionId)

Backend Connection Format

# In step dict:
step["input_connections"]["input_name"] = [
    {"id": output_step_id, "output_name": "output"},
    ...
]

Frontend → Backend Mapping

Frontend Connection:
  input: {stepId: 1, name: "input_file"}
  output: {stepId: 0, name: "output"}

→ Backend ConnectAction:
  input: {order_index: 1, input_name: "input_file"}  # or by label
  output: {order_index: 0, output_name: "output"}      # or by label

Recommendation: Typed Frontend Action Classes

Replace anonymous FactoryActions with typed classes for type-safe serialization:

class ConnectStepAction extends UndoRedoAction {
    constructor(
        private input: InputTerminal,
        private output: OutputTerminal,
        private connectionStore: WorkflowConnectionStore
    ) { ... }
}

class DisconnectStepAction extends UndoRedoAction { ... }

This enables instanceof routing in the serializer instead of matching on action.name === "connect steps".

9. Implementation Scope

Core Scope (Iteration 2-3)

Backend (Iteration 2):

1. RemoveStepAction schema + executor
2. position_absolute on UpdateStepPositionAction
3. StepReferenceById + union updates + _find_step fix
4. Size model
5. All 7 comment action schemas + executors
6. CommentReference model with _find_comment helper
7. Unit tests + integration tests

Frontend Serializer (Iteration 3):

1. Fix 5 null what values in SetValueActionHandler instances
2. Serializer for each mappable action type
3. Dispatcher routing by instanceof
4. Comprehensive serializer test suite

Deferred (Future)

1. Tool state serialization (complex, needs more research)
2. Action compaction/optimization
3. Concurrent editing / optimistic locking
4. Typed ConnectStepAction/DisconnectStepAction classes (recommended but can serialize FactoryAction by name initially)

10. Unresolved Questions

1. Step ID semantics: Frontend Step.id comes from step_dict["id"] which is order_index. StepReferenceById in plan says “database ID” but frontend doesn’t have DB PKs during editing. Should we use order_index as the “id” for now, or expose DB PKs to frontend?
2. Order_index gaps after removal: Backend _apply_add_step uses len(steps) for new order_index. If steps are sparse (gaps from removal), does this create collisions? May need max(keys) + 1 instead.
3. Comment position format: Comments use [x, y] tuples in JSON. Should AddCommentAction schema use Position model (with left/top) and have executor convert, or use a separate tuple-based model?
4. Workflow outputs on removed steps: Backend just removes the step dict (which contains workflow_outputs). Is that sufficient, or do we need to clean references from other steps/report markdown?
5. Connection FactoryAction serialization: Serialize by action.name === "connect steps" initially, or require typed classes first? Name-based is fragile but faster to implement.
6. LazySetValueAction for doi/readme/help/logoUrl/tags: These have no backend action equivalents. Should they return no-op from serializer, or do we need new backend actions?
7. Shared workflow access: Can shared-with users create journal entries, or owner-only? Depends on Galaxy’s access model.