# Workflow Migration Plan

## Goal

Bring `/workflows` to full production parity with the existing legacy render pipeline without breaking the current legacy path at any time.

## Current Status

- Phase 1 completed on canonical config storage, preset migration, and legacy-safe runtime extraction.
- Phase 2 completed on backend node registry, node definitions API, and schema-driven editor palette/settings.
- Phase 3 completed: `order_line_setup`, `resolve_template`, `material_map_resolve`, `auto_populate_materials`, `glb_bbox`, `output_save`, and `notify` are extracted behind the legacy task boundary, validated with targeted backend tests, and covered by workflow executor dispatch tests.

## Non-Negotiables

- The legacy render path remains operational throughout the migration.
- No existing output type or order flow may regress while the graph engine is introduced.
- Every node exposed in the workflow editor must have a backend-owned definition and a validated settings schema.
- New workflow definitions use one canonical JSON format.

## Canonical Workflow Model

```json
{
  "version": 1,
  "nodes": [
    {
      "id": "resolve_template",
      "step": "resolve_template",
      "params": {},
      "ui": {
        "type": "templateNode",
        "position": { "x": 420, "y": 120 },
        "label": "Resolve Template"
      }
    }
  ],
  "edges": [
    { "from": "setup", "to": "resolve_template" }
  ]
}
```

Notes:

- `step` and `params` are the backend-owned runtime model.
- `ui` is editor-only metadata and must not change runtime semantics.
- `edges` are mandatory for graph persistence and validation.

## Phases

### Phase 1: Canonical Model and Migration Base

- Finalize canonical workflow schema.
- Align frontend API types with backend schema.
- Add compatibility migration from preset configs to canonical DAG configs.
- Keep legacy dispatch as default.

### Phase 2: Node Registry

- Introduce a backend node registry as the single source of truth.
- Define labels, categories, descriptions, settings schemas, defaults, input contracts, and output contracts for every node.
- Expose node definitions over API for the editor.

### Phase 3: Extract Missing Legacy Steps

- Move inline legacy pipeline logic into explicit node executors/services.
- Required parity nodes:
  - `order_line_setup`
  - `resolve_template`
  - `material_map_resolve`
  - `auto_populate_materials`
  - `glb_bbox`
  - `output_save`
  - `notify`
- Optional but planned:
  - `threejs_render`

### Phase 4: Graph Runtime

- Introduce `WorkflowContext` and node-by-node execution with persistent run state.
- Support node outputs and artifact handoff across edges.
- Keep `legacy`, `graph`, and `shadow` execution modes.

### Phase 5: Workflow Editor Parity

- Persist and load `nodes`, `edges`, `step`, `params`, and `ui`.
- Render all node settings dynamically from backend schemas.
- Add validation, dry-run, dispatch, and run inspection.

### Phase 6: Shadow Mode and Rollout

- Run graph executions in parallel to the legacy flow for parity comparison.
- Compare status, outputs, media assets, notifications, and logs.
- Roll out per workflow or output type.

## Execution Modes

- `legacy`: current production path only
- `graph`: graph runtime is authoritative
- `shadow`: legacy remains authoritative, graph runs for comparison and observability

## Deliverables

- Canonical workflow schema and migration tooling
- Backend node registry and API
- Full editor support for all node settings
- Graph runtime with node-level execution and tracking
- Shadow mode parity checks

## Exit Criteria

- A workflow can be authored, validated, executed, and inspected entirely via `/workflows`.
- Legacy results and graph results match for defined golden cases.
- Legacy fallback is still available after graph rollout.