HartOMat/docs/workflows/NODE_CONTRACT_AUDIT_2026-04-12.md

Workflow Node Contract Audit

Stand: April 12, 2026

Scope

Geprüft wurden:

• backend/app/domains/rendering/workflow_node_registry.py
• backend/app/domains/rendering/workflow_schema.py
• backend/app/domains/rendering/workflow_graph_runtime.py
• frontend/src/components/workflows/workflowNodeContracts.ts
• frontend/src/components/workflows/WorkflowNodeInspector.tsx
• frontend/src/components/workflows/workflowGraphDraft.ts

Findings

1. Root-context inputs were modeled like normal upstream sockets

Betroffen:

• resolve_step_path mit cad_file_record
• order_line_setup mit order_line_record

Root cause:

• Das Backend seedingt diese Eingänge implizit aus dem Workflow-Kontext.
• Der Editor behandelte sie trotzdem als normale Canvas-Ports.

Folge:

• Entry-Nodes sahen aus, als müssten sie zusätzlich verkabelt werden.
• Das erzeugte genau die Art von unklaren Input-Anforderungen, die im aktuellen Workflow-Editor stören.

Maßnahme:

• Root-context inputs werden im Frontend separat als Kontextanforderung modelliert.
• Sie werden nicht mehr als normale verkabelbare Upstream-Sockets dargestellt.

2. Node authoring semantics were implicit instead of explicit

Root cause:

• Der Editor wusste bislang zwar, welche Felder und Ports existieren, aber nicht, welches Authoring-Muster eine Node eigentlich hat.

Folge:

• 0 inspector vars oder 1 input socket war im UI technisch korrekt, aber semantisch oft unverständlich.

Maßnahme:

• Nodes werden jetzt explizit als Context Entry, Connection-Driven, Inspector-Driven oder Hybrid beschrieben.

3. Registry coverage is broad, but some nodes are intentionally connection-only

Nodes mit 0 Inspector-Feldern:

• resolve_step_path
• occ_object_extract
• occ_glb_export
• thumbnail_save
• order_line_setup
• stl_cache_generate

Bewertung:

• Das ist nicht automatisch ein Defekt.
• Diese Nodes brauchen vor allem klare Authoring-Erklärung und keine künstlichen Dummy-Einstellungen.

4. Render/runtime parameter alignment is already strong for core render nodes

Der bestehende Testpfad deckt insbesondere für blender_still und blender_turntable bereits ab, dass deklarierte Felder von der Runtime unterstützt werden.

Nächste Lücke:

• systematische Prüfung der restlichen Bridge-/Output-Nodes gegen Runtime-Parameter und Template-Inputs

Current Batch Outcome

Batch A konzentriert sich zuerst auf:

1. sichtbaren 20-Block-Plan
2. Audit-Dokumentation
3. saubere Trennung von Root-Kontext und Upstream-Wiring
4. explizite Authoring-Semantik im Editor

Block 5 Inventory: Implicit Requirement Nodes

A. Korrekt feldlose Nodes, die nur bessere Authoring-Semantik brauchten

• resolve_step_path
  • echter Context Entry
  • braucht nur cad_file_record aus dem Workflow-Kontext
  • keine zusätzlichen Inspector-Variablen sinnvoll
• order_line_setup
  • echter Context Entry
  • braucht nur order_line_record aus dem Workflow-Kontext
  • liefert den Großteil des Order-Line-Arbeitskontexts
• occ_object_extract
  • reine Connection-Driven Node
  • braucht nur step_path
  • keine zusätzlichen lokalen Einstellungen in der Runtime vorhanden
• occ_glb_export
  • reine Connection-Driven Node
  • braucht nur step_path
  • Registry beschreibt bereits korrekt, dass per-Node-Tessellation-Overrides noch nicht existieren
• thumbnail_save
  • reine Connection-Driven Node
  • braucht nur rendered_image
  • Verhalten kommt aus dem angeschlossenen Thumbnail-Request, nicht aus lokalen Feldern
• stl_cache_generate
  • reine Connection-Driven Kompatibilitäts-Node
  • kein echter Produktionsschritt im HartOMat-Graph
  • Runtime ist bewusst ein compatibility_noop

B. Nodes ohne große Feldoberfläche, aber mit wichtiger Laufzeitsemantik

• output_save
  • hat nur wenige lokale Felder, aber relevante Handoff-Semantik
  • Verhalten hängt von angeschlossenen Render-Artefakten, Shadow/Graph-Mode und Publish-Handoff ab
  • UI muss klarer kommunizieren, wann diese Node pending, completed oder failed wird
• notify
  • hat nur minimale lokale Konfiguration, ist aber stark vom bewaffneten Render-Handoff abhängig
  • in shadow wird die Node bewusst unterdrückt
  • braucht vor allem bessere Preflight-/Inspector-Erklärung, nicht mehr Freitextfelder
• export_blend
  • aktuell nur ein bewusst schmaler Bridge-Export
  • nur Dateinamensuffix ist pro Workflow authorbar
  • größere Feldoberfläche wäre aktuell Fake-Konfiguration ohne Runtime-Nutzen

C. Nodes mit dynamischen statt statischen Inputs

• resolve_template
  • statische Inspector-Felder sind vorhanden
  • zusätzliche Inputs entstehen dynamisch über workflow_input_schema
  • das ist keine 0-Felder-Node, aber eine wichtige Ursache für Verwirrung, wenn Template-Inputs im Editor nicht klar sichtbar werden

D. Bewertung

• Für Batch A/B ist die Hauptlücke nicht "mehr Felder um jeden Preis".
• Die Hauptlücke ist:
  • Root-Kontext korrekt modellieren
  • Connection-vs-Inspector-Semantik explizit machen
  • Handoff-/Template-/Shadow-Semantik sichtbarer machen
• Echte neue Eingabevariablen werden erst dort ergänzt, wo Runtime und Template-System sie tatsächlich unterstützen.

Finding 5: notify had a real frontend/backend contract drift

Betroffen:

• Frontend-Authoring erlaubte export_blend -> notify
• Backend-Schema ließ notify bislang nicht auf blend_asset reagieren

Root cause:

• Frontend ergänzte blend_asset als alternatives requires_any
• Backend-Registry führte für notify nur Render-Artefakte und workflow_result

Folge:

• derselbe Graph konnte im Editor plausibel aussehen, aber beim Backend-Schema scheitern
• besonders Blend-Export-Workflows waren dadurch inkonsistent authorbar

Maßnahme:

• notify.input_contract.requires_any enthält jetzt auch blend_asset
• Registry führt blend_asset auch als konsumiertes Artefakt
• Schema- und Executor-Tests decken export_blend -> notify jetzt explizit ab

Finding 6: Bridge-node runtime params need explicit anti-drift guards

Betroffen:

• resolve_template
• material_map_resolve
• auto_populate_materials
• glb_bbox
• output_save
• notify

Root cause:

• Core-Render-Nodes waren bereits per Runtime-Key-Tests abgesichert.
• Bridge-Nodes hatten zwar Registry-Felder, aber keinen zentralen Runtime-Param-Contract gegen Drift.

Folge:

• zukünftige Änderungen in Runtime oder Registry könnten still auseinanderlaufen
• besonders gefährlich für Inspector-Felder, die klein wirken, aber produktionskritische Handoff-Semantik steuern

Maßnahme:

• Runtime-Key-Sets für die Bridge-Nodes wurden in workflow_graph_runtime.py zentralisiert
• Registry-Tests prüfen diese Nodes jetzt 1:1 gegen die Runtime

Ergebnis:

• Block 6 ist auf Contract-Ebene abgeschlossen
• weitere Batch-B-Arbeit kann sich jetzt auf Template-/Output-Semantik statt auf Grundsatzdrift konzentrieren

Finding 7: Template workflow inputs were only fully visible after forcing a concrete template override

Betroffen:

• resolve_template im Workflow-Inspector

Root cause:

• Template-definierte Produktionsvariablen kamen technisch aus workflow_input_schema, wurden im Editor aber primär erst nach Auswahl eines festen Template-Overrides sichtbar.
• Damit blieb ein Teil des realen Authoring-Vertrags für automatische Template-Auflösung zu implizit.

Folge:

• Autoren konnten schwer erkennen, welche Workflow-Variablen aktive Templates grundsätzlich bereits verlangen oder anbieten.
• Das machte Template-First-Graphen unnötig intransparent, obwohl die Runtime die Inputs bereits unterstützt.

Maßnahme:

• der Inspector zeigt jetzt zusätzlich eine automatische Abdeckungsansicht über aktive Templates mit Workflow-Inputs
• potenzielle Template-Variablen werden vor Auswahl eines festen Overrides als reale Produktionsvariablen sichtbar
• gezielte Frontend-Tests prüfen sowohl explizite Override-Inputs als auch die automatische Coverage

Finding 8: Render override fields could be edited although runtime discarded them

Betroffen:

• blender_still
• blender_turntable

Root cause:

• der Inspector behandelte mehrere renderautoritative Felder wie normale Node-Variablen
• die Runtime verwirft diese Werte jedoch bewusst, solange use_custom_render_settings deaktiviert bleibt und Output Type bzw. Template autoritativ sind

Folge:

• Autoren konnten Konfigurationen eingeben, die im Lauf keine Wirkung hatten
• das war eine echte Contract-Lücke zwischen UI und Runtime, nicht nur eine Darstellungsfrage

Maßnahme:

• renderautoritative Felder werden nun gesperrt, bis use_custom_render_settings aktiviert ist
• output_save und notify dokumentieren zusätzlich ihre Handoff-Semantik im Inspector explizit, um Shadow-/Graph-/Legacy-Verhalten klarer zu machen
• fokussierte Frontend- und Backend-Tests sichern diese Contract-Regeln gegen Regressions ab