# Workflow Validation Error Inventory

Stand: April 12, 2026

Dieses Inventar beschreibt die derzeit real existierenden Graph-Preflight- und Validation-Fehlerklassen im Workflow-System. Ziel ist, Backend-Preflight, Editor-Hinweise und Autoren-Debugging auf dieselbe Sprache zu bringen.

## Kategorien

### Context

Diese Fehler bedeuten, dass der Graph mit dem falschen Basiskontext oder mit einem ungültigen Kontext gestartet wird.

| Code | Severity | Root Cause | Erwartete Abhilfe |
| --- | --- | --- | --- |
| `invalid_context_id` | error | Die angegebene Context-ID ist keine UUID. | Gültige UUID aus Order Line oder CAD File verwenden. |
| `context_not_found` | error | Die UUID zeigt auf keinen vorhandenen Datensatz. | Vorhandenen Datensatz wählen oder Seed-/Import-Daten prüfen. |
| `context_kind_mismatch` | error | Workflow-Familie und übergebener Kontext passen nicht zusammen. | Order-Line-Graph mit Order Line starten, CAD-Graph mit CAD File. |
| `invalid_context_kind` | error | Einzelne Node verlangt `order_line`, der Graph läuft aber nicht in diesem Kontext. | Kontext oder Node-Familie korrigieren. |
| `cad_file_only_node` | error | CAD-Entry-Node wurde in einem Order-Line-Graph platziert. | Node in CAD-Workflow verschieben oder order-line-taugliche Alternative nutzen. |

### Setup Chain

Diese Fehler zeigen, dass die notwendige Vorbereitungslogik für den Renderpfad fehlt oder nicht renderbar ist.

| Code | Severity | Root Cause | Erwartete Abhilfe |
| --- | --- | --- | --- |
| `order_line_missing` | error | Order Line konnte nicht geladen werden. | Datensatz und FK-Kette prüfen. |
| `order_line_not_renderable` | error | Legacy-Setup erkennt harte Renderblocker. | Voraussetzungen der Order Line reparieren. |
| `order_line_skipped` | error | Legacy-Setup würde den Renderpfad bewusst überspringen. | Skip-Grund beseitigen. |
| `missing_order_line_setup` | error | Downstream-Node hat keinen vorgelagerten `order_line_setup`. | Setup-Node früher im Graph platzieren. |
| `setup_not_ready` | error | Setup ist vorhanden, aber nicht in einem lauffähigen Zustand. | Setup-Ursache beheben und erneut preflighten. |

### Data Source

Diese Fehler entstehen durch unvollständige oder nicht mehr erreichbare Eingabedaten.

| Code | Severity | Root Cause | Erwartete Abhilfe |
| --- | --- | --- | --- |
| `cad_file_missing_path` | error | CAD File hat keinen gespeicherten STEP-Pfad. | STEP-Referenz reparieren oder neu importieren. |
| `cad_file_step_missing` | error | Gespeicherter STEP-Pfad existiert auf dem Dateisystem nicht. | Storage-/Mount-/Importpfad reparieren. |
| `bbox_unresolved` | warning | Bounding Box konnte nicht aus GLB oder STEP abgeleitet werden. | GLB-Upstream, Exportpfad oder STEP-Quelle prüfen. |

### Runtime Gap

Diese Fehler bedeuten, dass der Graph aktuell noch keine echte Runtime-Implementierung für den Schritt hat.

| Code | Severity | Root Cause | Erwartete Abhilfe |
| --- | --- | --- | --- |
| `unsupported_node` | error | Node ist registriert, aber in der Graph-Runtime noch nicht ausführbar. | Legacy/Bridge behalten oder native Graph-Implementierung ergänzen. |

### Legacy Drift

Diese Warnungen markieren Stellen, an denen der Graph zwar laufen kann, aber vom bisherigen Legacy-Verhalten abweichen könnte.

| Code | Severity | Root Cause | Erwartete Abhilfe |
| --- | --- | --- | --- |
| `missing_resolve_template` | warning | Render-/Export-Pfad läuft ohne vorgelagertes `resolve_template`. | `resolve_template` vor Render-/Export-Nodes ergänzen. |
| `template_missing` | warning | Für die Order Line wurde kein Template aufgelöst. | Template zuordnen oder Override setzen. |

### Artifact Flow

Diese Klasse deckt aktuell generische Vertrags- und Upstream-Probleme ab, die aus Message oder Code als Artefaktfluss erkennbar sind.

| Erkennung | Severity | Root Cause | Erwartete Abhilfe |
| --- | --- | --- | --- |
| `code` oder `message` enthält `artifact` | meist warning/error | Ein benötigtes Artefakt wurde upstream nicht produziert oder nicht verbunden. | Fehlende Node/Verbindung ergänzen und Contract im Editor prüfen. |

## Blocking-Regeln

- `error` blockiert Graph-Dispatch.
- `warning` blockiert nicht automatisch, muss aber vor Rollout-Parität bewertet werden.
- `unsupported_node` ist inhaltlich ein Runtime-Gap und wird als blockierend behandelt.

## UI-Sprachregelung

- Editor und Preflight sollen immer beide Ebenen zeigen:
  - Schweregrad: `error`, `warning`, `info`
  - Typ: `Context`, `Setup Chain`, `Data Source`, `Runtime Gap`, `Legacy Drift`, `Artifact Flow`
- Action-Hints müssen immer direkt sagen, welche Node, welcher Kontext oder welche Upstream-Voraussetzung fehlt.

## Nächste Folgeschritte

1. Node-Katalog und Inspector mit denselben Kategorien annotieren.
2. Validation bereits im Authoring vor Preflight so früh wie möglich sichtbar machen.
3. Für echte `Artifact Flow`-Fehler langfristig explizite Codes statt Message-Heuristik einführen.