HartOMat/docs/workflows/NEXT_BATCH_ORCHESTRATION.md

Next Batch Orchestration

Goal

Define the next sensible implementation batch after the export/CAD contract audit, with work split for parallel execution and an integration order that keeps the legacy workflow operational.

Current Batch

Batch B1: Test Infrastructure Recovery

Purpose: Restore deterministic backend test execution so workflow parity work can be validated against real DB-backed tests again.

Why now:

• current targeted DB-backed tests fail on missing tables such as users and cad_files
• this blocks trustworthy validation for further workflow runtime work

Primary ownership:

• backend/tests/**
• backend/app/database.py
• backend/app/config.py only if required for test bootstrapping

Acceptance:

• targeted workflow tests create their schema reliably
• DB-backed pytest runs do not fail due to missing core tables
• no production runtime behavior changes unless strictly required for test setup correctness

Batch B2: Workflow Editor Authoring Organization

Purpose: Reduce authoring friction in /workflows by tightening node organization around family, module, and execution role while reclaiming canvas space.

Why now:

• the editor already has the needed primitives
• the remaining gap is structural clarity, not missing mechanics

Primary ownership:

• frontend/src/components/workflows/**
• frontend/src/pages/WorkflowEditor.tsx
• frontend/src/__tests__/components/workflowEditorUi.test.tsx

Acceptance:

• top-area clutter is reduced
• node discovery is cleaner by family/module grouping
• right-click insertion, edge deletion, align, dry-run, and run inspection still work

Batch B3: Canonical Still Path Smoke-Harness Closure

Purpose: Move the non-legacy still workflow closer to a runnable, documented smoke path without weakening legacy fallback.

Why now:

• backend graph/runtime coverage is already substantial
• the next risk is proving that the canonical still graph can be exercised as a stable rollout candidate

Primary ownership:

• backend/app/domains/rendering/**
• backend/app/domains/pipeline/tasks/**
• backend/tests/domains/test_workflow_*.py
• scripts/test_render_pipeline.py
• docs/workflows/** where needed

Acceptance:

• canonical still graph path has a bounded smoke route
• graph-vs-legacy safety remains explicit
• remaining blockers are documented as concrete runtime or fixture issues, not vague parity claims

Updated Immediate Next Batch

The next implementation batch should now be cut along contract and root-cause boundaries instead of UI-only slices.

Batch N1: Node-Contract Closure

Purpose: Make the backend node registry and workflow schema the authoritative source for graph family safety, parameter validity, and editor-visible node settings.

Why now:

• authoring UX is already good enough to build on
• remaining parity work depends on trustworthy backend-owned contracts

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

Acceptance:

• unknown node param keys are rejected deterministically
• family drift is blocked by schema validation
• every production-facing node has either a justified field schema or an explicit no-settings contract
• existing canonical still graph remains valid

Batch N2: Output-Type / Invocation Model Closure

Purpose: Finish the shift from legacy renderer flags to a real workflow invocation model with explicit family, artifact, and override semantics.

Why now:

• new output types and workflow-linked variants still depend on this contract being airtight
• this is the clean boundary between product configuration and runtime dispatch

Primary ownership:

• backend/app/domains/rendering/output_type_contracts.py
• backend/app/api/routers/output_types.py
• backend/app/domains/rendering/schemas.py
• backend/app/domains/rendering/models.py
• frontend/src/api/outputTypes.ts
• frontend/src/components/admin/OutputTypeTable.tsx

Acceptance:

• impossible workflow/artifact/family combinations are rejected early
• new output types can be created top-to-bottom as invocation profiles
• legacy-safe output types continue to render

Batch N3: CAD / Material Parity Root-Cause Closure

Purpose: Close the remaining instance- and part-key-related drift between CAD exporter, GLTF viewer, preview, and downstream render consumption.

Why now:

• this is still a real production blocker, not a polish item
• workflow parity stays superficial until geometry/material identity is stable

Primary ownership:

• 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/cadUtils.ts
• frontend/src/components/cad/ThreeDViewer.tsx
• frontend/src/components/cad/InlineCadViewer.tsx

Acceptance:

• viewer and manifest resolve the same authoritative material identity
• unresolved nodes are surfaced explicitly instead of silently using pseudo keys
• legacy preview and render behavior remain intact

Parallelization Rule

These three blocks should be prepared in parallel, but merged in order:

1. N1 first, because it establishes the source of truth for the other two.
2. N2 second, because it builds directly on those contracts.
3. N3 can be investigated in parallel, but should merge after N1 unless it proves fully isolated.

Gate For The Following Batch

For the updated immediate next batch, the following gate applies:

• N1 has deterministic backend validation and focused tests
• N2 preserves legacy-safe output types while tightening impossible combinations
• N3 proves the authoritative part/material identity chain with a focused low-RAM verification sequence

Current Execution Status

• N1 verified
  • focused checks green on April 10, 2026:
    • backend/tests/domains/test_workflow_schema.py
    • backend/tests/domains/test_workflow_node_registry.py
• N2 verified
  • focused checks green on April 10, 2026:
    • backend/tests/domains/test_output_types_api.py
    • frontend/src/__tests__/api/outputTypes.test.ts
• N3 in progress
  • April 10, 2026:
    • scene-manifest alias coverage expanded for exporter _af* suffix keys
    • order-line runtime now prefers authoritative scene-manifest assignments where manifest metadata exists
    • inline and fullscreen viewers now share the same manifest-plus-fallback merge contract
    • unresolved meshes are now surfaced explicitly in both viewers instead of silently disappearing behind pseudo keys
    • output-type authoring now consumes a backend-authored contract catalog for family/artifact/format/override constraints
  • next action: manual product-level parity check plus B04 node/module contract completion

Executable Block List

Die naechste sinnvolle Abarbeitung ist nicht mehr nach einzelnen Features, sondern nach stabilen Vertrags- und Produktionsgrenzen geschnitten.

Batch Wave W1: Identity And Contract Closure

• B01 CAD manifest alias closure
  • Ziel: scene-manifest und viewer auf denselben kanonischen semantischen part keys bringen
  • Fokus: exporter-style suffixe wie _af6, _af0_asm, dedup keys, alias inheritance
  • Status: abgeschlossen am April 10, 2026
  • Gate: backend/tests/test_part_key_service.py, backend/tests/test_export_step_to_gltf.py, frontend/src/__tests__/components/cadUtils.test.ts
• B02 CAD viewer/manifest convergence
  • Ziel: unresolved parts explizit sichtbar halten, aber alle autoritativ aufloesbaren parts im Viewer korrekt materialisieren
  • Fokus: ThreeDViewer, InlineCadViewer, logical part keys, reconciliation UX
  • Parallel zu: B03, B04
  • Status: abgeschlossen am April 10, 2026
  • April 10, 2026:
    • inline und fullscreen viewer auf denselben buildEffectiveViewerMaterials(...) contract gezogen
    • unresolved meshes werden explizit gezaehlt und sichtbar angezeigt statt pseudo-keys zu synthetisieren
    • focused gates gruen:
      • frontend/src/__tests__/components/cadUtils.test.ts
      • npm run build
      • ./scripts/workflow_sequential_gates.sh
  • Gate: manueller Produktcheck gegen reales CAD-Beispiel
• B03 Output-type authoring closure
  • Ziel: neue output types workflow-first und ohne hidden legacy assumptions anlegbar machen
  • Fokus: form-state, invocation overrides, artifact/family guards, defaults
  • Parallel zu: B02, B04
  • Status: abgeschlossen am April 10, 2026
  • April 10, 2026:
    • backend publiziert GET /api/output-types/contract-catalog als read-only Source of Truth fuer Family-, Artifact-, Format- und Override-Regeln
    • frontend/src/api/outputTypes.ts nutzt den Catalog mit lokalem Fallback statt Hardcode-Regeltabellen als primaere Truth
    • OutputTypeTable speist Family-, Artifact- und Rollout-Auswahl jetzt aus dem Backend-Catalog
    • focused gates gruen:
      • backend/tests/domains/test_output_types_api.py
      • frontend/src/__tests__/api/outputTypes.test.ts
      • frontend npm run build
      • ./scripts/workflow_sequential_gates.sh
  • Gate: backend/tests/domains/test_output_types_api.py, frontend/src/__tests__/api/outputTypes.test.ts
• B04 Node/module contract completion
  • Ziel: jede produktionsrelevante node hat einen klaren backend-owned settings/input/output contract
  • Fokus: registry metadata, no-settings contracts, family-safe validation
  • Gate: backend/tests/domains/test_workflow_schema.py, backend/tests/domains/test_workflow_node_registry.py

Batch Wave W2: Canonical Authoring Surface

• B05 Family-scoped node organization
  • Ziel: CAD, Bridge und Graph nodes im Editor klar trennen und suchbar halten
  • Fokus: family/module grouping, right-click search, low-noise discovery
  • Abhaengigkeit: B04
  • Status: abgeschlossen am April 10, 2026
  • April 10, 2026:
    • raw node catalog ist jetzt family-first organisiert: family -> module -> stage -> category
    • family/module runtime chips und stage scopes bleiben sichtbar, ohne zur stage-first Navigation zurueckzufallen
    • focused gates gruen:
      • frontend/src/__tests__/components/workflowNodeCatalog.test.ts
      • frontend/src/__tests__/components/workflowEditorUi.test.tsx
      • frontend npm run build
• B06 Authoring surface simplification
  • Ziel: eine gemeinsame authoring surface fuer canvas-menu, sidebar und starter paths
  • Fokus: shared controller/model statt mehrfacher UI-Sonderlogik
  • Abhaengigkeit: B04
  • Status: abgeschlossen am April 10, 2026
  • April 10, 2026:
    • workflowAuthoringSurface.ts kapselt jetzt shared section resolution, active-section validity und insert bindings als gemeinsame Surface-Controller-Logik
    • NodeCommandMenu und NodeDefinitionsPanel nutzen denselben Controller statt paralleler lokaler Section-/Insert-State-Implementierungen
    • focused gates gruen:
      • frontend/src/__tests__/components/workflowEditorUi.test.tsx
      • frontend/src/__tests__/components/workflowAuthoringGuidance.test.ts
      • frontend npm run build
• B07 Canvas ergonomics closure
  • Ziel: edge deletion, auto-align, reduced top-area clutter, faster insertion paths sauber zusammenziehen
  • Fokus: interaction consistency statt punktuelle UX-Patches
  • Abhaengigkeit: B06
  • Status: in Arbeit am April 10, 2026
  • April 10, 2026:
    • WorkflowCanvasToolbar auf kompaktere, wiederverwendbare Action-/Field-/Badge-Bausteine gezogen
    • Top-Area auf zwei dichtere Informationsreihen reduziert: Identitaet/Status oben, Context/Hint-Rail unten
    • focused gates gruen:
      • frontend/src/__tests__/components/workflowEditorUi.test.tsx
      • frontend npm run build
• B08 Starter graph and module bundle normalization
  • Ziel: starter blueprints, reference bundles und seed workflows auf dieselben kanonischen module paths ziehen
  • Fokus: still graph, CAD intake graph, bundle drift verhindern
  • Parallel zu: B07

Batch Wave W3: Runtime And Production Parity

• B09 Template-aware runtime unification
  • Ziel: legacy und graph nutzen dieselbe template/material/output orchestration
  • Fokus: template resolution, samples/transparency, publish semantics
  • Abhaengigkeit: B03, B04, B08
• B10 Non-legacy still smoke closure
  • Ziel: der kanonische still graph wird als wiederholbarer smoke path belastbar
  • Fokus: preflight, dispatch, authoritative output_save, failure visibility
  • Abhaengigkeit: B09
• B11 Template parity matrix
  • Ziel: graph vs legacy mit echten render-templates, output-varianten und alpha/sample settings vergleichen
  • Fokus: echte parity-beweise statt pillow-only checks
  • Abhaengigkeit: B09
• B12 CAD intake moduleization
  • Ziel: CAD import/extract/export/bbox/material-steps als echte workflow-module verfuegbar machen
  • Fokus: node-based production fuer intake workflows
  • Abhaengigkeit: B04, B08

Batch Wave W4: Operational Rollout

• B13 Rollout and fallback controls
  • Ziel: graph/shadow/legacy pro workflow und pro output type sicher steuerbar halten
  • Fokus: rollout mode, immediate rollback, operator clarity
  • Abhaengigkeit: B10, B11
• B14 Sequential E2E gates
  • Ziel: low-RAM, reproduzierbare smoke/golden/browser gates fuer /workflows
  • Fokus: sequenzielle statt parallele Verifikation
  • Abhaengigkeit: B10, B11, B13
• B15 Repo hygiene root-cause closure
  • Ziel: generated artifacts, root-owned caches und compose-side effects ursachenseitig schliessen
  • Fokus: ownership, pycache, build artifacts, helper script cleanup
  • Kann parallel laufen zu: B10 bis B14

Recommended Immediate Parallel Batch

Die naechste sinnvolle Batch mit minimalen Konflikten ist:

1. B02 lokal auf explizite unresolved-state-Fuehrung und viewer-level parity checks ziehen
2. B03 parallel als contract-catalog dedup zwischen Backend und Admin-UI bearbeiten
3. B15 parallel als Hygiene-Nebenstrang treiben

Danach:

1. B04
2. B05 bis B08 als Authoring-Welle
3. B09 bis B12 als Runtime-/Produktionswelle

Latest Verification

• April 10, 2026:
  • ./scripts/workflow_sequential_gates.sh gruen
  • backend runtime gates: 34 passed
  • frontend workflow/editor gates: 23 passed

Executable Next Queue

Die naechsten 12 Blöcke werden ab jetzt als eine gemeinsame Queue gefahren. Parallel bedeutet hier: Analyse, Vorbereitung und isolierte Teilpatches koennen parallel laufen. Merge und Verifikation bleiben bewusst sequentiell.

Queue Q2: Merge Order

1. B04-a Node text-contract validation

• Ziel: unvalidierte produktionsrelevante Text-Inputs im Registry-/Schema-Layer schliessen
• Scope: workflow_node_registry.py, workflow_schema.py, test_workflow_schema.py
• Gate: neue Schema-Tests fuer UUID, absolute Pfade, float-string, hex-color, suffix-format
• Status: abgeschlossen am April 10, 2026

2. B04-b Node registry invariants

• Ziel: defaults/fields/module_key/input-output-contracts als Registry-Invarianten pruefen
• Scope: test_workflow_node_registry.py
• Gate: registryweite Invariant-Tests gruen
• Status: abgeschlossen am April 10, 2026

3. B06 Shared authoring surface

• Ziel: gemeinsame Authoring-Schicht fuer Canvas-Menu, Sidebar und Starter-Aktionen
• Why now: verhindert doppelte UI-Logik in NodeCommandMenu und NodeDefinitionsPanel
• Status: abgeschlossen am April 10, 2026

4. B05 Family-scoped node organization
   • Ziel: modul-/family-basierte Node-Organisation auf der gemeinsamen Authoring-Schicht
   • Status: abgeschlossen am April 10, 2026
5. B07 Canvas ergonomics closure
   • Ziel: reduzierte Top-Area, konsistente Edge-/Insert-Interaktionen, Auto-Align sauber abschliessen
6. B08 Starter graph and module bundle normalization
   • Ziel: Blueprints, Bundles und New-Workflow-Einstieg auf dieselben kanonischen Pfade ziehen
7. B09 Template-aware runtime unification
   • Ziel: Graph und Legacy durch dieselbe Template-/Output-Orchestrierung fuehren
8. B10 Non-legacy still smoke closure
   • Ziel: kanonischer Still-Graph als wiederholbarer Smoke-Pfad mit klarer Fehlerflaeche
9. B11 Template parity matrix
   • Ziel: echte Graph-vs-Legacy-Vergleiche mit Render-Templates, Varianten und Alpha/Samples
10. B12 CAD intake moduleization

• Ziel: CAD-Import/Extract/Export/BBox als echte Production-Module im Editor und in der Runtime

11. B13 Rollout and fallback controls

• Ziel: Graph/Shadow/Legacy pro Workflow und Output-Type operativ steuerbar halten

12. B14 Sequential E2E gates

• Ziel: Low-RAM Golden-/Smoke-/Browser-Gates fuer /workflows

13. B15 Repo hygiene root-cause closure

• Ziel: generated artifacts, root-owned caches und compose side effects ursachenseitig schliessen
• Parallel vorbereitbar zu B09 bis B14

Queue Q2: Parallel Preparation Tracks

• Track A: Backend contracts
  • aktiv: B04-a, danach B04-b
  • Merge-Blocker fuer fast alle Folgearbeiten
• Track B: Frontend authoring refactor
  • Vorbereitung jetzt, Merge erst nach B04
  • Reihenfolge laut Analyse: B06 -> B05 -> B07 -> B08
• Track C: Runtime and parity
  • Investigation parallel moeglich
  • Merge-Reihenfolge: B09 -> B10 -> B11 -> B12 -> B13 -> B14
• Track D: Hygiene
  • Root-cause Sammlung und Script-Haertung parallel
  • Merge spaet, solange keine produktionskritische Blockade sichtbar wird

Queue Q2: Immediate Start

• Aktiver Implementierungsblock: B07
• Bereits abgeschlossene Merge-Slices in dieser Queue:
  • B04-a
  • B04-b
  • B06
  • B05
• Vorbereitete Folgeblöcke:
  • B07
  • B08