# First Wave Execution Plan ## Goal Translate the worker orchestration into concrete first patch slices that can be executed in parallel without breaking legacy rendering. This first wave is intentionally conservative: - close contract holes before broad UI refactors - avoid cross-cutting runtime rewrites in the same slice - keep all graph changes legacy-safe ## Current Codebase Snapshot ### Block A: Node Contracts Already in place: - node definitions already expose `family`, `module_key`, `execution_kind`, `input_contract`, `output_contract`, `artifact_roles_*`, and `legacy_source` - frontend already consumes node definitions and uses family-aware palette grouping - `glb_bbox` already gained a real editor field for `glb_path` Still missing: - backend workflow schema validation is still DAG-structural only - backend does not yet validate graph family consistency against the registry - backend does not yet validate node params against registry-owned field definitions - editor-visible nodes with weak or absent settings still need an explicit audit, especially export/CAD bridge nodes - status note: the canonical still-path bridge nodes have now been expanded with real settings for template override, material override/disable, auto-populate persistence controls, GLB source preference, output-save artifact expectations, and notify arming. The remaining audit emphasis is export/CAD parity rather than still-path hidden defaults. ### Block D: Output-Type Invocation Contracts Already in place: - `workflow_family`, `artifact_kind`, and `invocation_overrides` exist - backend already blocks mixed-family workflow links and direct family mismatches - frontend admin UI already exposes family, artifact kind, and workflow selection Still missing: - workflow selection can still communicate contract semantics more clearly - status note: backend now rejects workflow-family mismatches, mixed-family workflow links, and workflow/artifact mismatches against the linked workflow graph. The admin form has also been re-ordered into workflow-contract and invocation-profile sections so renderer details no longer dominate the first screenful. ### Block E: Editor Organization Already in place: - right-click canvas insertion exists - searchable node command menu exists - split of `legacy` / `bridge` / `graph` node groupings exists - auto-align exists - edge deletion exists via button, Delete key, right-click, and double-click - the workflow toolbar has been compressed so context, mode, authoring actions, and run actions sit in one compact canvas-adjacent strip Still missing: - the editor is feature-rich but still structurally busy - node insertion, run inspection, and inspector controls need clearer hierarchy - UX cleanup should follow contract cleanup so the editor does not encode unstable assumptions ### Block I: Rollout And Regression Gates Already in place: - `legacy`, `graph`, and `shadow` dispatch modes exist - graph mode falls back to legacy on failure - shadow mode keeps legacy authoritative - workflow comparison endpoint exists with hash, dimensions, and mean pixel delta reporting - there is meaningful backend coverage for shadow dispatch and comparison behavior - the live rollout harness now exposes `--workflow-still-smoke` and `--workflow-golden-suite` paths for canonical still and representative graph cases Still missing: - per-workflow and per-output-type rollout enablement is still an operational step, not yet a guided product workflow - smoke and golden harnesses still depend on live stack health and seeded render fixtures, so parity coverage is not yet CI-grade deterministic ## Parallel Patch Slices ### Slice A1: Registry-Backed Schema Validation Owner: - Block A worker Files: - `backend/app/domains/rendering/workflow_schema.py` - `backend/tests/domains/test_workflow_schema.py` - `backend/tests/domains/test_workflow_node_registry.py` Patch scope: - add backend validation that all nodes in a graph belong to one family unless explicitly allowed for migration - validate that node params only use keys declared by the node registry - return clear validation errors that name the offending node id, step, and param key Why this slice first: - it closes the largest backend contract gap without changing runtime execution - it gives Block D and Block E a stable source of truth to build on Acceptance: - a mixed-family graph without migration exemption is rejected - unknown node param keys are rejected - current canonical still graph remains valid ### Slice A2: Export/CAD Contract Audit Owner: - Block A worker Files: - `backend/app/domains/rendering/workflow_node_registry.py` - `backend/tests/domains/test_workflow_node_registry.py` Patch scope: - audit `occ_glb_export`, `export_blend`, `thumbnail_save`, and `stl_cache_generate` - add real field definitions only where runtime behavior genuinely supports editable inputs - avoid fake settings just to make the editor look complete Acceptance: - each audited node either has a justified field schema or an explicit no-settings contract backed by tests ### Slice D1: Artifact/Family Validation Tightening Owner: - Block D worker Files: - `backend/app/domains/rendering/output_type_contracts.py` - `backend/app/api/routers/output_types.py` - `backend/tests/domains/test_output_types_api.py` Patch scope: - define artifact-kind compatibility rules per workflow family - reject impossible combinations early in create/edit APIs - keep legacy output types renderable if they predate strict linkage Acceptance: - `cad_file` output types cannot declare order-line-only artifact kinds - invalid create/edit payloads fail with actionable errors - existing valid output types still load and render ### Slice D2: Workflow-First Output-Type Form Cleanup Owner: - Block D worker with light coordination from Block E Files: - `frontend/src/components/admin/OutputTypeTable.tsx` - `frontend/src/api/outputTypes.ts` Patch scope: - reorder the form to lead with family, workflow, artifact kind, then invocation overrides - visually separate invocation profile fields from legacy compatibility fields - preserve current API payload shape Acceptance: - a new output type can be created from top to bottom as a workflow invocation profile - renderer-specific detail fields no longer dominate the first screenful - status: completed with a four-section admin form (`Workflow Contract`, `Invocation Profile`, `Renderer Compatibility / Legacy Details`, `Catalog / Business`) while preserving the existing API payload and legacy fallback behavior ### Slice E1: Workflow Editor Header Simplification Owner: - Block E worker Files: - `frontend/src/components/workflows/WorkflowCanvasToolbar.tsx` - `frontend/src/pages/WorkflowEditor.tsx` - `frontend/src/__tests__/components/workflowEditorUi.test.tsx` Patch scope: - compress the oversized top area - move non-primary metadata into secondary badges or sidebar context - keep node insertion, align, save, dry-run, and run controls near the canvas Acceptance: - above-the-fold editor space is materially reduced - primary actions remain visible without scrolling - existing right-click and edge deletion behaviors remain intact ### Slice I1: Golden-Case Rollout Harness Owner: - Block I worker Files: - `scripts/test_render_pipeline.py` - `backend/tests/domains/test_workflow_dispatch_service.py` - `docs/workflows/WORKFLOW_DELIVERY_CHECKLIST.md` Patch scope: - add a canonical non-legacy still workflow smoke path to the render test script - record whether the run was legacy, graph, or shadow and surface comparison output when shadow is used - document the rollout gate needed before enabling graph mode on real output types Acceptance: - one command can exercise the canonical graph still path end to end - the script clearly reports whether rollout conditions were met or blocked ## Merge Order Inside First Wave 1. Slice A1 2. Slice D1 3. Slice A2 4. Slice D2 5. Slice E1 6. Slice I1 ## Integration Gates ### Gate FW-1 - Slice A1 merged - schema validation errors are deterministic and test-covered ### Gate FW-2 - Slice D1 merged - output-type API rules align with the tightened workflow contracts ### Gate FW-3 - Slice E1 merged - editor remains functionally complete after toolbar simplification ### Gate FW-4 - Slice I1 merged - canonical graph still smoke path is runnable and documented