werkjournal/docs/implementation/native-spike.md

Nativer Prototyp — optional zurückgestellt

Historischer Stand 2026-09-08. Native Image ist durch ausdrückliche Nutzerentscheidung optional zurückgestellt. Die reguläre JVM-Auslieferung und ihr abgeschlossener Nachweis stehen in runtime-spike.md; nachstehende offene native Prüfungen blockieren die erste Version nicht.

Bereits geprüft

• Gradle 9.3.0 Wrapper mit offiziellem SHA-256 erzeugt.
• Minimaler Kotlin-Flow-Screen, PWA-Offline-Seite und Versionsendpunkt erstellt.
• ./gradlew test bootJar -Pproduction=true --console=plain --no-daemon erfolgreich: HTTP-Test gegen echten eingebetteten Server und Versionsantwort-Test, Vaadin-Produktionsbuild und Spring-AOT-Verarbeitung. Dieser erste Nachweis lief auf JDK 21.
• Separates Debian-Bookworm-Rootfs mit GraalVM Community 25.3.4.1 erstellt. Offizielles GraalVM-Archiv anhand SHA-256 geprüft; JDK 25.0.4.1 aus dem extrahierten Image erfolgreich gestartet.
• Buildtoolchain anschließend auf JDK 25 vereinheitlicht, Bytecode-Ziel bleibt 21. Die JVM-Tests mit dieser endgültigen Build-JVM bestehen ebenfalls, einschließlich HTTP-Abruf von PWA-Manifest und Service Worker (Testbericht vom 2026-09-08, 17:37 UTC).

Noch nachzuweisen

• Nativer Compile-Erfolg mit den begrenzten Ressourcen und vollständiger PWA-Starttest ohne JDK auf Bookworm. Der erste, unbegrenzte Build kompiliert und startet bereits; sein PWA-Test scheitert (siehe unten).
• Tatsächlicher Build in Werkdock auf der vereinbarten CI-Instanz; derzeit nur Rootfs lokal erzeugt. Instanz noch nicht verändert und Werkjournal noch nicht als CI-Repository registriert.
• Begrenzter Ressourcenverbrauch auf der Buildinstanz, geeignete Rootfs-Bereitstellung sowie Trixie-Prüfung vor Hostwechsel.
• Native Frontend-/PWA-Ressourcen in der laufenden Anwendung.

Keine öffentliche Bereitstellung dieser ungesicherten Prototypversion. OIDC, Datenbank, Push und Fachfunktionen folgen in ihren eigenen Knoten.

Werkdock- und Ressourcennachweis

Das ergänzte Rootfs enthält Python für tools/smoke-native; der komprimierte Stand ist etwa 463 MiB groß. Das Debian-Basisimage ist auf Digest 88200866dfff7ea7f5cbcb6ec7c8a701889efe6fe859fe64d6990e4b07ea4171 fixiert. Neue Standard-Rootfsnamen enthalten den Dockerfile-Hash, damit Werkator nach Rezeptänderungen nicht versehentlich ein altes importiertes Image verwendet.

Lokal mit Werkdock 0.1-Generation tatsächlich gestartet: Bookworm 12.15, GCC 12.2, GraalVM Community JDK/native-image 25.0.4.1 und Python 3.11.2. Import in projektlokalen Store unter work/, keine Änderung fremder Images.

CI-Host: Werkdock doctor besteht 7/7 Prüfungen. Paketquota ist nun geprüft: rund 5 GiB genutzt bei 8 GiB Soft-/12 GiB Hardlimit auf dem betreffenden Dateisystem. Noch keine Rootfsübertragung oder CI-Registrierung durchgeführt.

Der erste lokale native Lauf (noch ohne neue Begrenzungen) hat die Reachability-Analyse erfolgreich mit rund 4.12 GiB Heap abgeschlossen und Codegenerierung erreicht. Für die CI sind deshalb nativeHeap=2g und nativeThreads=2 als explizite, überschreibbare Buildgrenzen ergänzt; Gradle 512 MiB und zwei Worker, Kotlin-Compiler im Gradle-Prozess. Ob diese Grenzen genügen, muss ein eigener Lauf zeigen. Kein ressourcenintensiver Build auf dem gemeinsamen CI-Host gestartet, bevor diese Frage geklärt ist.

tools/smoke-native startet die Binärdatei mit leerer Anwendungsumgebung und isoliertem Arbeitsverzeichnis, prüft Versionsantwort, Flow-HTML und Offline-Ressource und beendet den Prozess auch bei Fehlern. Der Fehlerpfad mit /bin/false und der grundlegende native Start sind geprüft; der vollständige PWA-Test steht noch aus.

tools/ci-native fasst den späteren Werkator-Build in einem geordneten Kommando zusammen: JVM-Tests, native Kompilierung, Starttest, danach Release-Binärdatei und Manifest mit Commit, Version, SHA-256 und libc. Kein Deployment wird dadurch ausgelöst. Der Ablauf wird erst nach erfolgreichem Werkdock-Vergleich als ausgeführt gewertet.

Ergebnis des ersten nativen Builds

Erster nativer Compile erfolgreich: 11m59s Native-Image-Zeit, 13m03s Gradle-Gesamtzeit, 5.29 GiB Peak RSS, 136.88 MiB ausführbare Datei. GraalVM erzeugt zusätzlich .so-Begleitbibliotheken; der Releaseablauf muss diese mitliefern und einzeln hashen.

Versionsendpunkt, Flow-HTML und Offline-Seite bestehen den Starttest unter Bookworm-Werkdock mit ausgeblendetem /opt/graalvm. Der erweiterte PWA-Test scheitert jedoch: /manifest.webmanifest liefert keine JSON-Antwort. Die native Klassenressourcensuche protokolliert fehlende Nachbarklassen des Anwendungspakets; deshalb ist dies ausdrücklich noch kein vollständiger PWA-Nachweis.

Als gezielte Korrektur wird das vollständige Anwendungspaket als Klassenressource registriert (ApplicationResourceHints). Ein neuer Lauf mit JDK 25, JVM-Regressionsprüfung für Manifest/Service Worker und den begrenzten Ressourcen läuft in der lokalen Bookworm-Werkdock-Sandbox. Wirksamkeit der Korrektur erst nach dem nativen Test behaupten.

Systembibliotheken des ersten Artefakts

ldd in der Bookworm-Werkdock-Sandbox mit ausgeblendetem JDK löst für das Hauptprogramm libc und libz auf. Die mitgelieferten Headless-AWT-/Bildbibliotheken benötigen zusätzlich libm und libdl; ihre Java-/JVM-Shims liegen neben dem Programm. Diese Shims sind native Begleitbibliotheken, keine benötigte JDK-Installation.

Die ebenfalls erzeugten X-AWT-, Font- und Soundbibliotheken melden im minimalen Rootfs fehlende X11-Bibliotheken, libfreetype und libasound. Das beweist noch keine Laufzeitabhängigkeit der Webanwendung von allen diesen Bibliotheken. Insbesondere die PWA-Icon-Erzeugung muss aber im nativen Smoke-Test erfolgreich ausgeführt werden, bevor die tatsächlich nötigen Laufzeitpakete feststehen. Keine pauschale Aussage, dass alle erzeugten Bibliotheken bereits vollständig nutzbar sind.

Vorbereitete Werkator-Definition

.werkator.yml definiert den benannten Job native für main: sauberer Build, JVM-Tests, nativer Compile und PWA-Smoke-Test über tools/ci-native. Die gemeinsame default-Definition hat keinen eigenen Trigger. Es gibt noch keinen Deployment-Schritt; dieser gehört zum späteren Betriebsknoten.

Das Rootfs wird vor Registrierung des Repositories unter .git/werkator/buildenv/werkjournal-buildenv-bookworm-graal25.3.4.1-abd04988b226.tar.zst bereitgestellt und per SHA-256 mit dem lokalen Archiv verglichen. abd04988b226 bezeichnet das Dockerfile-Rezept. Werkator importiert das Archiv außerhalb des Builds, bevor die vertraulichen Git-Verzeichnisse im Sandbox-Mount maskiert werden. Auf dem CI-Host ist builds.default.werkdock.binary in der Maschinenkonfiguration auf den absoluten vorhandenen Werkdock-Pfad zu setzen, da der nichtinteraktive PATH das Werkzeug nicht enthält.

Nur Berichte und Release-Dateien sind als öffentliche Buildartefakte vorgesehen. Die Konfiguration hält den jüngsten Build und zusätzlich den letzten erfolgreichen Build. Dies ersetzt keine spätere Deployment-Rückfallversion mit passender Datenbanksicherung. YAML lokal geparst; der echte Werkator-Lauf ist noch nicht erfolgt.

Begrenzter Build: 2 GiB

Die JVM-Tests bestehen, aber die native Analyse erreicht mit 2 GiB keinen Abschluss. Diagnose am laufenden Compiler: Old Generation 100 %, Eden 96,81 %, 153 Full GCs mit insgesamt 428,7 Sekunden Full-GC-Zeit. Der Versuch wurde daraufhin gezielt per SIGTERM beendet (Gradle Exit 1, Native-Image Exit 143 nach insgesamt 15m26s). Dies war ein bewusster Abbruch wegen beobachteter Heap-Sättigung, kein behaupteter OutOfMemoryError.

Nächster lokaler Vergleich: tools/ci-native -PnativeHeap=3g, weiterhin zwei Threads. Die Standardgrenze bleibt bis zum Ergebnis unverändert. Auf dem CI-Host wurde kein Compiler gestartet. Das Buildskript übernimmt optionale Gradle-Argumente, erfasst den Quellcommit vor dem Build und entfernt alte Release-Dateien, damit ein fehlgeschlagener Neubau keine veralteten Release-Artefakte hinterlässt.

Ergebnis des 3-GiB-Vergleichs und Werkbaum-Abgleich

Der lokale Werkdock-Lauf mit 3 GiB Heap und zwei Threads ist nach 15m45s mit java.lang.OutOfMemoryError: Java heap space beendet. Native Image liefert Exit 3, Gradle Exit 1. Die registrierten zusätzlichen Klassenressourcen sind deshalb weiterhin nicht nativ verifiziert. Kein neuer Build läuft.

Der Nutzer bestätigt: Werkbaum verwendet derzeit keinen GraalVM-Native-Build, sondern ein über tools/remote backend install-jdk heruntergeladenes JDK. Damit ist dessen bisheriger Build kein Vergleich für den nativen Speicherbedarf von Werkjournal.

Die rein lesende Werkator-Messung zeigte 4917 MiB Gesamt-RAM, 2438 MiB verfügbar und 1717 MiB belegten Swap. Das ist eine Momentaufnahme, keine RAM-Reservierung für Builds. Der Werkator-Dienst war aktiv, sein MemoryCurrent lag bei etwa 434 MiB; aktueller Memory-Pressure avg10 war 0. Auf diesem Host wurde kein Werkjournal-Build gestartet.

Entscheidung erforderlich: native Architektur mit größerem Build-Speicherbudget fortsetzen oder wie Werkbaum ein eigenes JDK für die Anwendung verwenden. Letzteres verändert die vereinbarte native Auslieferung; es wird nicht ohne Nutzerentscheidung umgesetzt. Laufzeit-RAM und PWA-Verhalten bleiben in beiden Fällen zu prüfen.