# 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`