253 lines
8.2 KiB
Markdown
253 lines
8.2 KiB
Markdown
# 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
|