HartOMat/docs/workflows/FIRST_WAVE_EXECUTION.md

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