HartOMat/docs/workflows/WORKERS.md

Workflow Worker Orchestration

Purpose

This file defines the parallel work split to bring /workflows to full production-capable parity while keeping the legacy workflow operational at all times.

The orchestration is intentionally contract-first:

1. stabilize runtime and output-type contracts
2. formalize module-backed node definitions
3. organize editor authoring around those contracts
4. prove parity with dual-run and golden-case validation

Non-Negotiable Constraints

• Legacy workflow dispatch must remain callable throughout the migration.
• Mixed-family graphs may exist for migration visibility, but new authoring must converge on family-safe graphs.
• No worker may revert unrelated user changes in the dirty worktree.
• cad_file and order_line concerns must be separated explicitly in contracts, editor palette organization, and output-type validation.
• A worker may only edit files in its assigned ownership scope unless the handoff section explicitly allows expansion.

Shared Acceptance Baseline

Each worker block is only complete when all of the following hold:

• targeted tests for the touched scope pass
• legacy-safe behavior is preserved or explicitly guarded with fallback
• the changed API surface is reflected in frontend/backend types where applicable
• docs and seed/default data stay aligned with the runtime behavior

Branching And Commit Order

Suggested branch naming:

• workflow/block-a-node-contracts
• workflow/block-b-module-unification
• workflow/block-c-starter-graphs
• workflow/block-d-output-type-contracts
• workflow/block-e-editor-organization
• workflow/block-f-run-inspection
• workflow/block-g-parity-golden-cases
• workflow/block-h-cad-material-parity
• workflow/block-i-rollout-regression-gates

Preferred integration order:

1. Block A
2. Block D
3. Block B
4. Block C
5. Block E
6. Block F
7. Block H
8. Block G
9. Block I

Worker Blocks

Block A: Node Contract Closure

Purpose: Turn the node registry into the canonical module contract source for every editor-visible graph node.

Primary ownership:

• backend/app/domains/rendering/workflow_node_registry.py
• backend/app/domains/rendering/workflow_schema.py
• backend/tests/domains/test_workflow_node_registry.py
• backend/tests/domains/test_workflow_schema.py
• frontend/src/api/workflows.ts

Tickets:

• audit every editor-visible node for missing or weak param schemas
• close real settings gaps for graph-authorable nodes, especially export and CAD bridge nodes
• make family, module_key, input_contract, output_contract, artifact_roles_*, and legacy_source authoritative and complete
• strengthen family-aware graph validation in the backend schema layer

Acceptance criteria:

• every editor-visible node has a machine-usable contract
• no node required for still-render parity is missing editable settings
• backend rejects family-invalid graphs with clear errors

Dependencies:

• none

Block B: Module Unification

Purpose: Route graph and legacy execution through the same reusable production-module layer wherever parity nodes already exist.

Primary ownership:

• backend/app/domains/rendering/workflow_runtime_services.py
• backend/app/domains/rendering/workflow_executor.py
• backend/app/domains/rendering/workflow_graph_runtime.py
• backend/app/domains/rendering/tasks.py
• backend/app/domains/pipeline/tasks/render_order_line.py
• backend/tests/domains/test_workflow_graph_runtime.py
• backend/tests/domains/test_workflow_runtime_services.py

Tickets:

• reduce duplicate behavior split across legacy task code and graph adapters
• ensure async task wrappers are transport, not business-logic owners
• close remaining drift for still, turntable, and blend export paths

Acceptance criteria:

• graph and legacy call the same module behavior for extracted parity nodes
• parity bug fixes land once in the shared module layer
• fallback to legacy still works on graph failure

Dependencies:

• Block A

Block C: Canonical Starter Graphs And Seeds

Purpose: Keep live workflow definitions, blueprints, and starter templates aligned with the corrected canonical graphs.

Primary ownership:

• backend/app/domains/rendering/workflow_config_utils.py
• backend/app/domains/rendering/workflow_builder.py
• backend/app/api/routers/admin.py
• frontend/src/api/workflows.ts
• seed/migration helpers and related tests

Tickets:

• maintain canonical cad_file and order_line starter graphs
• backfill or normalize existing seeded workflow definitions safely
• prevent drift between backend canonical graphs and frontend starter generation

Acceptance criteria:

• starter workflows are family-safe and match backend canonical topology
• existing seeded workflows can be repaired without manual DB surgery
• frontend new-workflow creation matches backend canonical graph shape

Dependencies:

• Block A

Block D: Output-Type Invocation Contracts

Purpose: Turn output types into explicit workflow invocation profiles instead of loose legacy renderer presets.

Primary ownership:

• backend/app/models/output_type.py
• backend/app/domains/rendering/output_type_contracts.py
• backend/app/api/routers/output_types.py
• backend/alembic/versions/065_output_type_workflow_contracts.py
• backend/alembic/versions/066_output_type_invocation_overrides.py
• backend/tests/domains/test_output_types_api.py
• frontend/src/api/outputTypes.ts
• frontend/src/components/admin/OutputTypeTable.tsx

Tickets:

• finalize explicit workflow_family, artifact_kind, and invocation override semantics
• validate output-type and workflow compatibility in create/edit flows
• separate productized invocation settings from raw legacy render settings
• make create/edit UX workflow-first instead of renderer-first

Acceptance criteria:

• new output types can be created reliably against the real backend contract
• invalid workflow-family or artifact combinations are blocked early
• legacy output types remain renderable without forced migration

Dependencies:

• Block A

Block E: Workflow Editor Organization

Purpose: Make the editor usable for production authoring by organizing nodes around families and modules instead of a flat mixed palette.

Primary ownership:

• frontend/src/pages/WorkflowEditor.tsx
• frontend/src/components/workflows/
• frontend/src/__tests__/components/

Tickets:

• organize palette and search around family, module, and execution role
• support low-friction node insertion from canvas context actions
• reduce top-of-page control bloat and move graph actions closer to the canvas
• improve graph readability with automatic alignment/layout and cleaner inspector behavior
• preserve delete/edit flows for nodes and edges

Acceptance criteria:

• authoring a family-safe graph is materially faster than today
• node discovery works from both sidebar and canvas-local actions
• editor UX follows the backend-owned contracts instead of bespoke per-node logic

Dependencies:

• Block A
• Block D for workflow-first output-type interactions that deep-link into editor usage

Block F: Run Inspection And Workflow Debugging

Purpose: Make /workflows operationally useful by exposing preflight, dispatch, run records, node outputs, and failure surfaces cleanly.

Primary ownership:

• backend/app/domains/rendering/workflow_router.py
• backend/app/domains/rendering/models.py
• backend/app/domains/rendering/schemas.py
• frontend/src/api/workflows.ts
• frontend/src/components/workflows/
• runtime/run inspection tests

Tickets:

• complete workflow run inspection UI
• expose node-level statuses, outputs, timings, and key artifacts
• make preflight and manual dispatch part of the normal debugging flow

Acceptance criteria:

• a failed graph run can be debugged from /workflows without jumping through ad hoc DB inspection
• node-level outputs are visible enough to diagnose broken contracts and missing artifacts

Dependencies:

• Block A
• Block B

Block G: Golden-Case Parity Suite

Purpose: Prove graph parity against legacy for representative render cases before broad rollout.

Primary ownership:

• scripts/test_render_pipeline.py
• parity fixtures, comparison tooling, and integration tests
• docs/workflows/WORKFLOW_DELIVERY_CHECKLIST.md

Tickets:

• define representative still, turntable, blend, and failure golden cases
• automate legacy-vs-graph comparison for outputs and key side effects
• capture artifacts and logs needed for regression triage

Acceptance criteria:

• golden cases pass for at least one real still-render graph and one legacy fallback path
• parity regressions are reproducible and attributable to specific nodes or contracts

Dependencies:

• Block B
• Block C
• Block F
• Block H for CAD/material-sensitive cases

Block H: CAD/Material Parity

Purpose: Restore parity for GLTF/USD preview identity, material assignment, and instance-aware part mapping so graph workflows consume trustworthy geometry state.

Primary ownership:

• backend/app/api/routers/cad.py
• backend/app/api/routers/products.py
• backend/app/domains/pipeline/tasks/export_glb.py
• backend/app/domains/pipeline/tasks/extract_metadata.py
• backend/app/services/part_key_service.py
• frontend/src/components/cad/InlineCadViewer.tsx
• frontend/src/components/cad/ThreeDViewer.tsx
• frontend/src/components/cad/cadUtils.ts
• CAD/material tests

Tickets:

• close instance-aware part identity drift in viewer and export pipeline
• restore reliable missing-material assignment and library mapping
• ensure graph nodes consume the same geometry/material truth as legacy-render preparation

Acceptance criteria:

• product preview and GLTF viewer show consistent material assignment on representative legacy products
• manual material repair workflows remain intact
• downstream render nodes receive stable part/material identities

Dependencies:

• Block A
• Block B

Block I: Rollout And Dual-Run Regression Gates

Purpose: Keep graph rollout safe by enforcing shadow-mode parity checks, fallback behavior, and rollback paths per workflow/output type.

Primary ownership:

• backend/app/domains/rendering/dispatch_service.py
• backend/app/domains/rendering/workflow_comparison_service.py
• backend/tests/domains/test_workflow_dispatch_service.py
• rollout docs and runbooks

Tickets:

• formalize shadow-mode regression gates
• make rollout decisions per workflow or output type
• preserve immediate rollback to legacy
• encode comparison thresholds and operational readiness checks

Acceptance criteria:

• shadow mode can run on representative workflows without affecting authoritative outputs
• rollout and rollback are explicit and test-backed
• graph error handling stays at or below legacy operational risk

Dependencies:

• Block B
• Block G

First-Wave Parallelization

Run these blocks in parallel first:

• Block A: Node contract closure
• Block D: Output-type invocation contracts
• Block E: Editor organization audit and contract-driven UX split
• Block I: Rollout and dual-run regression gate design

Reason:

• they have the highest leverage on all remaining work
• they define the contracts the later E2E and parity work must obey
• they are separable enough to run in parallel with minimal file overlap if ownership is respected

Cross-Block Handoffs

• Block A hands canonical node/module contracts to Blocks B, C, E, and H.
• Block D hands stable output-type invocation semantics to Blocks E and I.
• Block H hands trustworthy geometry/material identity to Blocks G and I.
• Block F and G jointly define ship-readiness for /workflows.

Quality Gates By Orchestration Stage

Stage 1: Contract Gate

• Blocks A and D merged
• backend and frontend contracts aligned
• new workflows and new output types validate against the same source of truth

Stage 2: Runtime Gate

• Block B merged
• canonical starter graphs from Block C verified
• no regression in legacy dispatch behavior

Stage 3: Authoring Gate

• Block E and Block F merged
• /workflows supports real authoring, preflight, dispatch, and inspection

Stage 4: Parity Gate

• Block H and Block G merged
• at least one non-legacy still-render workflow passes end to end against a representative product

Stage 5: Rollout Gate

• Block I merged
• shadow mode, rollback, and comparison thresholds are operationally usable