⚡ ZELYRA 1.2.40 | Handbuch (Druck & PDF-Ausgabe)
← Zurück zur Webansicht ⭳ EPUB

ZELYRA HANDBUCH

Vollständige Sprachdokumentation & Technische Referenz
Zelyra 1.2.40 (Commit aa49733)
Offizielle Dokumentation · Stefan Siedelmann
https://siedelmann.com · October 2026

Das Zelyra-Handbuch

Von den Grundlagen bis zur datenbankgestützten Webanwendung. Absicht beschreiben. Korrektheit beweisen.

Willkommen beim vollständigen Zelyra-Handbuch. Es umfasst sowohl das didaktische Lehrbuch »Zelyra lernen – Verständlich programmieren von den Grundlagen bis zur eigenen Anwendung« (Teil I bis X, Kapitel 1 bis 43) als auch das technische Referenzhandbuch (Abschnitte 1 bis 40) sowie ausführliche Anhänge (A bis K).

Zelyra 1.2.39: aktueller Funktionsumfang

Dieses Handbuch beschreibt den Stand des zuletzt veröffentlichten stabilen Releases Zelyra 1.2.39 (Stand: 21. Oktober 2026). Änderungen nach diesem Release werden erst dann als verfügbar beschrieben, wenn sie veröffentlicht sind. Zelyra 1.0.0 war die erste stabile Hauptveröffentlichung; die Sprachkompatibilitätslinie bleibt 0.1. Der Umfang einzelner Compiler-, Datenbank-, Betriebs- und IDE-Funktionen ist in den jeweiligen Abschnitten mit ihren Grenzen beschrieben. Das frühere Werkzeug zelyra migrate laravel wurde in 1.1.2 entfernt. Der davon getrennte, spätere zelyra import laravel-Workflow analysiert ausgewählte Projektstrukturen und erzeugt prüfbare Zelyra-Grundlagen; er portiert keine vollständige Laravel-Webanwendung.

Änderungen seit Version 1.0.0

Release-Details: Die vollständige Liste der veröffentlichten Versionen steht in den Zelyra-Releases auf GitHub. Die Studio-Anleitung, Logs-Anleitung, Deinstallationsleitfaden, Mail-Anleitung und Datenbankmatrix beschreiben weitere Funktionen und Grenzen.

Entwicklungsstand und vereinbarte Architektur

Zelyra befindet sich im stabilen Release 1.2.39 mit aktiver Weiterentwicklung. Den laufenden Stand und offene Ziele hält die Zelyra-Roadmap fest.

Zeitpläne und Outbox im Betrieb

In Zelyra-Projekten richtet das System bei der Bereitstellung alle erforderlichen Outbox- und Scheduler-Tabellen idempotent ein. Der residente Scheduler wird automatisch gestartet, sobald das Projekt über den Dienst (zelyra service) oder zelyra serve betrieben wird.

Folgende Befehle stehen zur Inspektion und Verwaltung bereit:

zelyra check main.zyl
zelyra task list main.zyl
zelyra schedule list main.zyl
zelyra schedule jobs main.zyl
zelyra schedule status main.zyl

Ein manueller Cron-Eintrag auf dem Host (crontab -e) ist für den regulären Betrieb nicht erforderlich. Für den Fall, dass ein bestehendes externes Überwachungssystem oder ein externer Server-Scheduler die Zelyra-Befehle ansteuern soll, kann mit:

zelyra schedule export main.zyl --format cron --output deploy/zelyra.cron

eine exportierbare Cron-Vorschau erzeugt werden. zelyra schedule export überschreibt keine vorhandene Datei und greift nicht in die System-Crontab ein. Die unterstützten Umgebungsvariablen stehen in der Environment-Referenz; die detaillierte Scheduler- und Task-Architektur wird in Kapitel 28 behandelt.

Statuszeichen

Inhaltsverzeichnis

Zelyra lernen – Das Lehrbuch

Technisches Referenzhandbuch

Anhänge

TEIL I – ZELYRA UND PROGRAMMIERUNG VERSTEHEN

Kapitel 1: Willkommen bei Zelyra

1. Was lerne ich in diesem Kapitel?

In diesem Einführungskapitel erfährst du:

2. Warum ist das Thema wichtig?

Bevor du die erste Zeile Code schreibst, solltest du verstehen, welches Problem Zelyra löst. Kennst du das Gefühl, wenn ein winziger Buchstabendreher in Zeile 412 erst am Freitagabend um 17:03 Uhr im Produktivbetrieb bemerkt wird – just in dem Moment, in dem du die Jacke anziehen wolltest? In der modernen Softwareentwicklung herrscht oft ein heilloses Durcheinander: Man modelliert eine Tabelle in SQL, schreibt dieselben Regeln noch einmal in einem Backend-Framework (wie Laravel, Express oder Django), validiert dieselben Daten ein drittes Mal im Frontend (HTML/JavaScript) und hofft inständig, dass alle Schichten synchron bleiben. Zelyra bricht mit dieser Fragmentierung: Du beschreibst dein Datenmodell, deine Regeln und deine Schnittstellen an einer einzigen Stelle – und Zelyra leitet daraus geprüfte, sichere Bausteine ab. Keine doppelten Definitionen, keine Synchronisationskatastrophen und vor allem: entspanntere Freitagnachmittage.

3. Verständliche Erklärung

Eine Programmiersprache ist wie ein präzises Regelwerk. Sie erlaubt es dir, einem Computer eindeutige Anweisungen zu geben. Computer sind unfassbar schnelle Rechenknechte, glänzen aber durch die vollständige Abwesenheit von gesundem Menschenverstand: Wenn du einem Computer sagst: »Lauf zum Bäcker und kauf ein Brot, und wenn sie Eier haben, bring zehn mit«, kommt er im Zweifel mit zehn Broten zurück. In Zelyra nimmt der Compiler dich und den Rechner an die Hand, damit genau solche Missverständnisse gar nicht erst kompiliert werden.

Zelyra ist eine statisch typisierte Sprache. Das bedeutet: Der Compiler prüft Typen beim Übersetzen und kann bestimmte Typkonflikte vor der Ausführung melden. Welche weiteren Regeln er prüft, hängt vom implementierten Prüfumfang ab; eine Fehlerfreiheit des Programms garantiert das nicht.

Gleichzeitig ist Zelyra datenbank- und webzentriert:

4. Kleine, aufeinander aufbauende Beispiele

Schauen wir uns ein erstes winziges Zelyra-Programm an:

# Unser erstes Zelyra-Programm: Eine Begrüßung
fn main() {
    print("Willkommen bei Zelyra!")
}

Wenn du diesem Programm mehr Struktur geben möchtest, zerlegst du die Aufgabe in eine Funktion:

fn begruessen(name: String) -> String {
    return "Hallo, " + name + "! Willkommen in der Zelyra-Welt."
}

fn main() {
    nachricht = begruessen("Entwickler")
    print(nachricht)
}

Kommentare: # und ##

# beginnt einen Zeilenkommentar. Er kann am Zeilenanfang oder hinter einer Anweisung stehen und reicht bis zum Zeilenende. Ein Blockkommentar wird durch zwei ##-Begrenzer eingeschlossen. Die Begrenzer stehen jeweils allein auf einer Zeile; der Inhalt darf mehrere Zeilen umfassen. Blockkommentare sind nicht verschachtelt. # innerhalb einer Zeichenkette gehört zum Text.

# Ein Zeilenkommentar
##
Dieser Text ist ein Blockkommentar.
Er kann mehrere Zeilen umfassen.
##
fn main() {
    print("Hallo") # Kommentar hinter einer Anweisung
    print("# bleibt innerhalb der Zeichenkette sichtbar")
}

Die bestehende Schreibweise // bleibt kompatibel. Verwende in neuen Beispielen #. Die kompakte Schreibweise ## Text ## auf derselben Zeile ist im dokumentierten Lexer kein Blockkommentar über mehrere Zeilen; verwende für einen Block die oben gezeigten alleinstehenden Begrenzer.

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Zelyra verbindet Datenmodell, Logik und Oberfläche in einer einzigen klaren Sprache.
  2. Was du meinst, steht im Code: Keine versteckte Magie, keine impliziten Null-Werte.
  3. Der Compiler meldet erkannte Syntax- und Typfehler vor der Ausführung. Laufzeitfehler und nicht abgedeckte Prüffälle bleiben möglich.

7. Übungsaufgaben

8. Praxisaufgabe: Der Grundstein der Aufgabenverwaltung

In diesem Buch bauen wir Schritt für Schritt eine echte, praxistaugliche Aufgabenverwaltung (Task Management). Wir beginnen mit dem einfachsten Schritt: Erstelle eine Datei aufgaben_start.zyl, die den Namen unseres Systems und die Versionsnummer sauber auf dem Bildschirm ausgibt:

fn main() {
    system_name = "Zelyra TaskManager"
    app_version = "0.9.9"
    print(system_name + " (Version " + app_version + ") gestartet.")
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Was unterscheidet eine statisch typisierte Sprache von einer dynamischen Sprache?
  2. Warum ist es ein Vorteil, wenn Tabellenschemata direkt in der Programmiersprache definiert werden?
  3. Warum sind unveränderliche Werte standardmäßig sicherer als veränderliche Variablen?

Kapitel 2: Wie ein Programm funktioniert

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Programmierfehler zu beheben ist kinderleicht, wenn man versteht, an welcher Station des Compilers der Fehler gemeldet wird. Ein Computer ist im Grunde ein extrem fleißiger, aber erschreckend wörtlich nehmender Assistent: Er tut haargenau das, was du ihm aufschreibst – niemals das, was du dir insgeheim dabei gedacht hast. Ein Syntaxfehler bedeutet, dass der Text unlesbar ist (wie ein Rezept, in dem »Salz« mit drei Konsonanten geschrieben wurde); ein Typfehler bedeutet, dass die Logik widersprüchlich ist (wie der Versuch, Milch zu braten); ein Laufzeitfehler bedeutet, dass während der Ausführung eine unvorhergesehene Bedingung eintrat. Wenn du diese Kette verstehst, verlierst du jegliche Scheu vor Fehlermeldungen: Der Compiler ist kein schlecht gelaunter Türsteher, sondern dein treuer Pair-Programming-Partner.

3. Verständliche Erklärung

Ein Computerprozessor versteht nur Nullen und Einsen (Maschinencode). Wenn wir Menschen eine Textdatei mit Zelyra-Code schreiben (z. B. programm.zyl), durchläuft dieser Text mehrere Stationen:

Quelltext (.zyl)
   │
   ▼
[1. Lexer]: Zerlegt den Text in Wörter/Symbole (Tokens)
   │
   ▼
[2. Parser]: Baut einen logischen Strukturbaum (AST = Abstract Syntax Tree)
   │
   ▼
[3. Type Checker]: Prüft alle Typen, Namen und Berechtigungen
   │
   ▼
[4. Verifier]: Beweist mathematisch Schleifen und Verträge (Contracts)
   │
   ▼
[5. Runtime / Interpreter]: Führt die geprüften Anweisungen aus

4. Kleine, aufeinander aufbauende Beispiele

Ein einfacher Algorithmus zur Berechnung der verbleibenden Tage bis zu einer Frist:

fn tage_bis_ziel(ziel_tag: Int, aktueller_tag: Int) -> Int {
    verbleibend = ziel_tag - aktueller_tag
    return verbleibend
}

fn main() {
    heute = 10
    abgabe = 24
    tage = tage_bis_ziel(abgabe, heute)
    print(tage)
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Der Lexer liest Zeichen, der Parser versteht Strukturen, der Type Checker prüft den Sinn.
  2. Je früher ein Fehler abgefangen wird (beim Prüfen statt beim Kunden), desto günstiger und sicherer ist die Software.
  3. Jedes Programm folgt dem Grundmuster: Eingabe empfangen, nach klaren Regeln verarbeiten, Ergebnis ausgeben.

7. Übungsaufgaben

8. Praxisaufgabe: Aufgaben-Priorität berechnen

In unserer Aufgabenverwaltung müssen wir die Dringlichkeit einer Aufgabe einstufen. Wenn weniger als 3 Tage verbleiben, ist die Aufgabe dringend:

fn ist_dringend(verbleibende_tage: Int) -> Bool {
    return verbleibende_tage <= 3
}

fn main() {
    frist_in_tagen = 2
    dringend = ist_dringend(frist_in_tagen)
    if dringend {
        print("Achtung: Aufgabe hat hohe Prioritaet!")
    } else {
        print("Aufgabe liegt im normalen Zeitplan.")
    }
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. An welcher Stelle der Toolchain wird bemerkt, dass ein Anführungszeichen fehlt?
  2. Was bedeutet das EVA-Prinzip?
  3. Warum bricht ein statisch typisiertes Programm ab, wenn man Text und Zahl fehlerhaft verbindet?

Kapitel 3: Zelyra installieren und einrichten

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Eine reibungslos funktionierende Werkzeugkette ist die Grundlage jeder erfolgreichen Entwicklungsarbeit. Wenn Befehle nicht gefunden werden oder Umgebungsvariablen fehlen, verliert man wertvolle Zeit. Zelyra bringt einen schlanken, benutzerlokalen Installer mit, der ohne fremde Paketmanager oder Root-Rechte auskommt. Zudem führt der neue Web-Setup-Assistent Einsteiger visuell durch die Initialisierung von Datenbank und Containern.

3. Verständliche Erklärung

Zelyra benötigt für einfache Programme weder Apache noch fremde Laufzeiten. Das Zelyra-CLI (zelyra) ist ein einzelnes, hochoptimiertes Binärprogramm.

Je nach Betriebssystem wählst du den passenden Weg:

  1. Linux / macOS: Hier lädst du das offizielle Repository herunter und führst ./install.sh aus (oder lädst ein Release-Archiv). Zelyra wird benutzerlokal in ~/.local/bin installiert. Für Docker nutzt man unter Linux die offizielle Docker-Engine-Anleitung und unter macOS Docker Desktop für Mac.
  2. Windows: Unter Windows stehen install.ps1 für PowerShell sowie install.cmd zur Verfügung. Für vollständige MariaDB-Projekte wird Docker Desktop für Windows mit aktivierter Compose-Unterstützung empfohlen.
  3. Plattform-Docker-Prüfung: Zelyra installiert Docker bewusst nicht eigenmächtig und fordert keine Root-Rechte an. Vor dem Start von Compose-Diensten prüfst du deine Umgebung einfach mit docker compose version. Fehlt Compose oder fehlen Berechtigungen auf den Docker-Socket, gibt Zelyra gezielte Plattform-Hilfestellungen aus.

4. Kleine, aufeinander aufbauende Beispiele

Schritt 1: Zelyra installieren Aus dem Quelltext (Linux / macOS):

git clone https://github.com/sf1976/zelyra.git
cd zelyra
./install.sh

Oder direkt als vorkompiliertes Release ohne Rust-Toolchain:

./install.sh --release v1.2.39

Unter Windows (PowerShell):

git clone https://github.com/sf1976/zelyra.git
Set-Location zelyra
.\install.ps1 -Release v1.2.39

Schritt 2: Vollständige Version und Hilfe prüfen

zelyra --version
zelyra --help

zelyra --version gibt den vollständigen Compiler- und Paketversionsstand aus (z. B. zelyra 1.2.39). Die Sprachkompatibilitätslinie bleibt 0.1.

Schritt 3: Docker Compose prüfen (für MariaDB-Projekte)

docker compose version

Schritt 4: Systemdiagnose ausführen

zelyra doctor

Dieser Befehl analysiert Umgebung, Pfade, Ports und Werkzeuge. Mit zelyra doctor --json erhältst du strukturierte Maschinendaten für IDEs.

Schritt 5: Geführter Web-Setup-Assistent (Optional) In jedem MariaDB-Projektverzeichnis kannst du den grafischen Assistenten starten:

zelyra setup --web

Zelyra öffnet einen lokalen HTTP-Server auf 127.0.0.1:3030 mit einem zufälligen, einmaligen Sicherheitstoken. Dort kannst du mit einem Klick die .env-Konfiguration erzeugen, den MariaDB-Container starten und das Datenbankschema anwenden.

zelyra setup richtet die MariaDB-Umgebung ein. Ein Minimalprojekt, das mit zelyra init ohne --mariadb angelegt wurde, läuft direkt mit zelyra run main.zyl und benötigt diesen Setup-Schritt nicht. Pfade werden wörtlich interpretiert: Nach mkdir test_a zeigt ./test_a auf diesen Ordner; /test_a bezeichnet unter Linux dagegen einen Ordner direkt unter dem Dateisystemstamm. Existiert nur der relative Ordner, schlägt die CLI ihn als Pfadkorrektur vor.

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Das Zelyra-CLI bündelt Compiler, Runner, Formularprüfer, Webserver und Setup-Assistenten in einem einzigen Werkzeug.
  2. Mit docker compose version und zelyra doctor überprüfst du jederzeit den Zustand deiner Toolchain.
  3. Das Release kann mit --release v1.2.39 direkt ohne Rust-Compiler installiert werden.
  4. zelyra setup --web bietet eine intuitive, browserbasierte Ersteinrichtung mit sicherem Einmal-Token.

7. Übungsaufgaben

8. Praxisaufgabe: Die Arbeitsumgebung für den TaskManager vorbereiten

Lege auf deinem Rechner einen neuen Ordner für unser Projekt an und teste, ob die Zelyra-Toolchain dort ordnungsgemäß funktioniert:

mkdir mein-taskmanager
cd mein-taskmanager
echo 'fn main() { print("TaskManager-Umgebung bereit.") }' > test.zyl
zelyra check test.zyl
zelyra run test.zyl

Wenn die Ausgabe TaskManager-Umgebung bereit. erscheint, ist dein System perfekt vorbereitet!

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welcher Befehl zeigt alle verfügbaren CLI-Optionen an?
  2. Warum benötigt Zelyra für Konsolen- und Web-Programme keinen externen Webserver wie Apache?
  3. Was prüft der Befehl zelyra doctor?

Kapitel 4: Das erste Zelyra-Projekt

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Sobald Programme mehr als zehn Zeilen umfassen, gehören sie in eine saubere Projektstruktur. Eine gut organisierte Ordnerstruktur stellt sicher, dass Konfigurationen, Datenbankmodelle, Web-Routen und Geschäftslogik ihren festen Platz haben. Wer von Beginn an Projekte standardisiert anlegt, spart sich später aufwändige Aufräumarbeiten.

3. Verständliche Erklärung

Mit dem Befehl zelyra new <projektname> erzeugst du ein schlüsselfertiges Projekt:

Automatische Portvergabe: Sind die Standardports 3000 (Web) oder 3306 (MariaDB) auf deinem Entwicklungsrechner bereits belegt, scannt Zelyra automatisch und vergibt freie Ports in der neu erzeugten .env.

Optionale Feature-Schalter: Du kannst in zelyra.toml oder .env Teilbereiche aktivieren oder deaktivieren:

[features]
web = true
api = true
crud = true
auth = true
audit = true

Wird ein deaktivierter Bereich im Code genutzt, meldet der Compiler verlässlich E-FEATURE-001. Die wirksame Konfiguration kannst du jederzeit mit zelyra config main.zyl (oder --format=json) geheimnisfrei inspizieren.

4. Kleine, aufeinander aufbauende Beispiele

Projekt erstellen (Minimal oder MariaDB):

# Minimales Skriptprojekt:
zelyra new taskmanager --template minimal
cd taskmanager

# Oder vollständiges MariaDB-Webprojekt:
zelyra new taskmanager-web --mariadb
cd taskmanager-web

Ersteinrichtung mit einem einzigen Befehl:

zelyra setup --all

Dieser Befehl legt eine geschützte .env an, startet die MariaDB-Container-Umgebung und wendet das Schema an.

Projektkonfiguration prüfen:

zelyra config main.zyl

Projekt prüfen und starten:

zelyra check main.zyl
zelyra run main.zyl

Projekt automatisch formatieren:

zelyra fmt main.zyl

zelyra fmt sorgt dafür, dass aller Zelyra-Code im gesamten Team exakt denselben, sauberen Gestaltungsregeln folgt.

Weitere dokumentierte CLI-Befehle für den Projektalltag:

zelyra verify main.zyl
zelyra db plan main.zyl
zelyra editor

zelyra verify führt die unterstützten Vertrags- und Invariantenprüfungen aus; Kapitel 19 erklärt ihre Reichweite. zelyra db plan zeigt geplante Schemaänderungen. Prüfe diesen Plan, bevor du Änderungen mit zelyra db apply übernimmst; Kapitel 24 beschreibt den Ablauf. zelyra editor startet Zelyra Studio.

Die aktuelle CLI-Referenz führt weder einen Unterbefehl zelyra test noch separate Programme zelyrac build oder zelyra lsp auf. Assertions beschreibst du mit assert(...) in einer ausführbaren .zyl-Datei und startest sie mit zelyra run; einen eigenen Test-Runner dokumentiert die Referenz nicht.

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. zelyra new erstellt eine saubere, standardisierte Projektstruktur.
  2. In zelyra.toml werden Name, Version und benötigte Berechtigungen (Capabilities) verwaltet.
  3. zelyra fmt garantiert einen einheitlichen, gut lesbaren Programmierstil.

7. Übungsaufgaben

8. Praxisaufgabe: Die Aufgabenverwaltung als echtes Projekt initialisieren

Erstelle das Projekt, das uns durch das gesamte Buch begleiten wird:

zelyra new zelyra-tasks --template minimal
cd zelyra-tasks

Schreibe in main.zyl ein erstes Menü:

fn zeige_menue() {
    print("=================================")
    print("   ZELYRA AUFGABENVERWALTUNG     ")
    print("=================================")
    print("1: Alle Aufgaben anzeigen")
    print("2: Neue Aufgabe anlegen")
    print("3: Programm beenden")
}

fn main() {
    zeige_menue()
}

Prüfe das Projekt mit zelyra check main.zyl und führe es mit zelyra run main.zyl aus.

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Wozu dient die Datei zelyra.toml?
  2. Warum ist zelyra fmt in Teams so wertvoll?
  3. Wann benötigt ein Zelyra-Programm eine main()-Funktion?

TEIL II – DIE GRUNDLAGEN DER SPRACHE

Kapitel 5: Werte und Datentypen

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Im echten Leben kann man Äpfel nicht mit Birnen addieren. Ein Computer würde ohne Typen jedoch genau das tun: Er würde versuchen, eine Postleitzahl mit einem Stundensatz zu multiplizieren oder einen Buchstabensalat als Datum zu interpretieren. Wer schon einmal erlebt hat, wie ein System Geldbeträge als Fließkommazahl (Float) speicherte und 0.10 € + 0.20 € plötzlich zu 0.30000000000000004 € wurden, weiß: Buchhalter und Finanzämter haben für solche quantenmechanischen Rundungsüberraschungen erstaunlich wenig Sinn für Humor. In Zelyra verhindert das Typsystem solche Absurditäten von vornherein.

3. Verständliche Erklärung

Jeder Wert in Zelyra besitzt einen Typ. Du kannst den Typ entweder explizit hinschreiben oder Zelyra ihn automatisch aus dem zugewiesenen Wert ableiten lassen:

fn main() {
    # Explizite Typangabe: Name gefolgt von Doppelpunkt und Typ
    anzahl: Int = 10

    # Automatische Typableitung: Zelyra erkennt sofort, dass dies ein String ist
    titel = "Wichtige Besprechung"

    print(titel)
}

Die wichtigsten Datentypen in Zelyra:

4. Kleine, aufeinander aufbauende Beispiele

fn main() {
    aufgabe_id: Int = 101
    aufgabe_name: String = "Server aktualisieren"
    ist_erledigt: Bool = false
    geschaetzte_stunden: Float = 2.5
    stundensatz: Float = 85.50

    print(aufgabe_name)
    print(ist_erledigt)
}

Zelyra schützt vor unpassenden Typen: Wenn du versuchst, aufgabe_id = "einhundert" zu schreiben, verweigert der Compiler sofort den Dienst mit E-TYPE-001.

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Datentypen schützen davor, unpassende Informationen miteinander zu verknüpfen.
  2. Für Geldbeträge gilt: Immer Decimal, niemals Float.
  3. Zelyra kann Typen intelligent ableiten, aber explizite Typen dokumentieren deine Absicht.

7. Übungsaufgaben

8. Praxisaufgabe: Aufgaben-Attribute definieren

Erweitere unser Aufgabenprojekt in main.zyl. Definiere die typisierten Grunddaten einer Aufgabe:

fn main() {
    task_id: Int = 1
    task_name: String = "Datenbankschema pruefen"
    is_done: Bool = false
    priority: Int = 1 # 1 = hoch, 2 = mittel, 3 = niedrig

    print("Aufgabe #" + "1" + ": " + task_name)
    if is_done {
        print("Status: Erledigt")
    } else {
        print("Status: Offen (Prioritaet: hohe Dringlichkeit)")
    }
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Warum sollte man für Geldwerte Decimal statt Float verwenden?
  2. Was ist der Unterschied zwischen "Z" und 'Z'?
  3. Welche beiden Werte kann ein Bool annehmen?

Kapitel 6: Variablen und Unveränderlichkeit

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Einer der häufigsten Gründe für schwer auffindbare Softwarefehler in Sprachen wie JavaScript, Python oder C++ ist unkontrollierte Veränderbarkeit: Eine Funktion verändert heimlich eine globale Variable, und an ganz anderer Stelle stürzt das Programm ab – der gefürchtete »Gestern ging es noch und niemand hat was angefasst«-Effekt. Veränderlicher Zustand hat in Entwicklerteams schon mehr Freundschaften ruiniert als die endlose Debatte über Tabs versus Leerzeichen. Zelyra folgt einem radikal klaren Prinzip: Feste Werte sind der Normalfall. Ein Wert, der sich niemals hinter deinem Rücken ändern kann, stiftet auch keine heimliche Verwirrung. Wenn sich ein Wert während der Programmlaufzeit ändern darf, musst du das ganz bewusst mit dem Schlüsselwort mutable ankündigen.

3. Verständliche Erklärung

Stell dir eine Variable wie eine beschriftete Schachtel im Arbeitsspeicher vor:

Gültigkeitsbereich (Scope): Variablen leben immer nur innerhalb des Blocks { ... }, in dem sie deklariert wurden. Wird der Block verlassen, vergisst Zelyra die Variable automatisch. Das schont den Speicher und verhindert Namenskonflikte.

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Unveränderlichkeit schützt vor versehentlichem Überschreiben

fn main() {
    projekt = "Zelyra Kern"
    # projekt = "Neues Projekt" // FEHLER: Compiler blockiert Zuweisung an unveränderliche Variable!
    print(projekt)
}

Beispiel 2: Wann mutable sinnvoll ist (z. B. Zähler und Schleifen)

fn main() {
    mutable offene_aufgaben = 5
    print(offene_aufgaben)

    # Eine Aufgabe wurde erledigt:
    offene_aufgaben = offene_aufgaben - 1
    print(offene_aufgaben)
}

Beispiel 3: Gültigkeitsbereiche (Scopes)

fn main() {
    bereich = "Global im main"
    if true {
        lokal = "Nur im if sichtbar"
        print(lokal)
        print(bereich)
    }
    # print(lokal) // FEHLER: `lokal` existiert außerhalb des Blocks nicht mehr!
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. In Zelyra sind Werte standardmäßig unveränderlich.
  2. Wenn sich ein Wert ändern darf, steht mutable sichtbar davor.
  3. Variablen existieren nur innerhalb ihres deklarierten Blocks { ... }.

7. Übungsaufgaben

8. Praxisaufgabe: Zähler für unsere Aufgabenverwaltung

In unserer Aufgabenverwaltung wollen wir zählen, wie viele Aufgaben noch zu erledigen sind:

fn main() {
    mutable anzahl_offen = 3
    print("Start: Aufgaben zu erledigen: ")
    print(anzahl_offen)

    # Erste Aufgabe erledigt:
    anzahl_offen = anzahl_offen - 1
    print("Zwischenstand: Noch offen:")
    print(anzahl_offen)

    # Zweite Aufgabe erledigt:
    anzahl_offen = anzahl_offen - 1
    print("Endstand: Noch offen:")
    print(anzahl_offen)
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Was passiert, wenn du einer Variablen ohne mutable einen neuen Wert zuweist?
  2. Warum ist Unveränderlichkeit ein Sicherheitsmerkmal?
  3. Kann eine Variable aus einem inneren Block außerhalb dieses Blocks gelesen werden?

Kapitel 7: Operatoren und Ausdrücke

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Programme bestehen nicht nur aus festen Werten, sondern berechnen Ergebnisse, treffen Vergleiche und kombinieren logische Aussagen. Ein Operator ist das Bindeglied, das aus einzelnen Werten neue Erkenntnisse formt. Wer Operatoren beherrscht, kann komplexe Geschäftsregeln präzise in einfache Ausdrücke übersetzen – und verhindert peinliche Rechenpannen, bei denen durch eine vergessene Klammer plötzlich jeder Kunde 100% Rabatt erhält, nur weil heute Dienstag ist.

3. Verständliche Erklärung

Rechenoperatoren:

Vergleichsoperatoren (liefern immer Bool):

Logische Operatoren:

4. Kleine, aufeinander aufbauende Beispiele

fn main() {
    # Rechnen
    grundzeit = 60
    puffer = 15
    gesamtzeit = grundzeit + puffer
    print(gesamtzeit)

    # Vergleichen
    ist_lang = gesamtzeit > 60
    print(ist_lang)

    # Logische Verknüpfung
    hat_puffer = puffer > 0
    ist_kritisch = gesamtzeit > 120 && !hat_puffer
    print(ist_kritisch)
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Zuweisen mit =, Vergleichen mit ==.
  2. Rechnungen werten Punkt vor Strich aus; setze im Zweifel Klammern für maximale Klarheit.
  3. && verlangt beidseitige Wahrheit, || gibt sich mit einer zufriedenen Bedingung zufrieden.

7. Übungsaufgaben

8. Praxisaufgabe: Fristen- und Status-Prüfung im TaskManager

In unserem TaskManager müssen wir prüfen, ob eine Aufgabe überfällig ist und sofortige Aufmerksamkeit verlangt:

fn main() {
    tage_verbleibend = -2
    ist_erledigt = false
    ist_blockiert = false

    # Eine Aufgabe ist ueberfaellig, wenn Tage < 0 und sie noch nicht erledigt ist
    ist_ueberfaellig = tage_verbleibend < 0 && !ist_erledigt

    # Hohe Dringlichkeit: Ueberfaellig und nicht durch andere blockiert
    braucht_eingriff = ist_ueberfaellig && !ist_blockiert

    print("Aufgabe ueberfaellig?")
    print(ist_ueberfaellig)
    print("Braucht sofortigen Eingriff?")
    print(braucht_eingriff)
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Was ist der Unterschied zwischen = und ==?
  2. Welches Ergebnis liefert der Ausdruck 5 > 3 && 2 > 10?
  3. Wofür steht der Operator %?

Kapitel 8: Ein- und Ausgaben

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Ein Programm, das weder Daten empfangen noch Ergebnisse mitteilen kann, ist für den Anwender nutzlos. Ein- und Ausgaben (I/O) verbinden die Logik deines Codes mit der Außenwelt. Weil Zugriffe auf Tastatur, Festplatte oder Netzwerk aber auch Sicherheitsrisiken darstellen, regelt Zelyra diese Zugriffe viel kontrollierter als ältere Sprachen.

3. Verständliche Erklärung

Terminalzugriff ist eine Capability. Die aufrufende Funktion muss uses Console deklarieren. In Projekten mit einer [capabilities]-Sektion muss zusätzlich console = true gesetzt werden; neue Projektvorlagen lassen die Freigabe standardmäßig aus. Konsoleneingabe ist für zelyra run gedacht. Webanwendungen verwenden stattdessen typisierte Requests und Formulare. Die Eingabe wird nicht verborgen; nutze read_console() daher nicht für Passwörter oder andere Geheimnisse.

fn main() uses Console {
    datum = read_console("Datum: ")
    match datum {
        Some(wert) => {
            print("Eingegeben: " + wert)
        }
        None => {
            print("Keine Eingabe.")
        }
    }
}

[capabilities]
console = true

4. Kleine, aufeinander aufbauende Beispiele

Ausgabe formatieren:

fn main() {
    titel = "Release 1.0"
    prozent = 80
    print("Fortschritt fuer " + titel + ":")
    print(prozent)
}

Eingabe über Funktionsparameter und Umgebungsvariablen:

fn verarbeite_aufgabe(titel: String, prioritaet: Int) {
    print("Bearbeite: " + titel)
    print("Prioritaetsstufe:")
    print(prioritaet)
}

fn main() uses Environment {
    modus = env("APP_MODUS")
    print("Aktueller Modus:")
    print(modus)
    verarbeite_aufgabe("Backup erstellen", 1)
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. print() gibt Werte verlässlich auf der Konsole aus.
  2. Eingaben fließen über Parameter, Umgebungsvariablen, Dateien, Terminal oder Web-Routen.
  3. Systemzugriffe benötigen die passende Capability (z. B. uses Environment).

7. Übungsaufgaben

8. Praxisaufgabe: Ausgabeformatierung für den TaskManager

Erstelle eine Ausgabefunktion für unsere Aufgabenverwaltung:

fn drucke_kopfzeile(bereich: String) {
    print("----------------------------------------")
    print("BEREICH: " + bereich)
    print("----------------------------------------")
}

fn drucke_aufgabe_eintrag(nr: Int, titel: String, erledigt: Bool) {
    print("Aufgabe Nr: ")
    print(nr)
    print("Titel: " + titel)
    if erledigt {
        print("Status: [X] ERLEDIGT")
    } else {
        print("Status: [ ] OFFEN")
    }
    print("----------------------------------------")
}

fn main() {
    drucke_kopfzeile("HEUTIGE AUFGABEN")
    drucke_aufgabe_eintrag(1, "Handbuch durcharbeiten", true)
    drucke_aufgabe_eintrag(2, "Zelyra-Beispiele ueben", false)
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welche Funktion nutzt man in Zelyra für Textausgaben?
  2. Warum verlangt der Zugriff auf env() die Angabe uses Environment?
  3. Welche Eingabewege sind in serverbasierten Zelyra-Anwendungen typisch?

Kapitel 9: Entscheidungen mit Bedingungen

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Ohne Bedingungen wäre jedes Programm starr wie eine Spieluhr: Es würde stur immer dieselbe Melodie dudeln. Wirklich nützlich wird Software erst, wenn sie auf unterschiedliche Situationen reagiert: Ist der Nutzer eingeloggt? Ist die Frist abgelaufen? Reicht das Guthaben oder versucht der Kunde gerade, minus fünf Pizzen in den Warenkorb zu legen? Mit if und match verleihst du deinem Code echtes Urteilsvermögen – und mit Zelyras exhaustivem match passt der Compiler auf, dass du keinen einzigen Sonderfall unter den Tisch fallen lässt.

3. Verständliche Erklärung

4. Kleine, aufeinander aufbauende Beispiele

Einfache Verzweigung:

fn main() {
    offen = 0
    if offen == 0 {
        print("Super! Alle Aufgaben sind erledigt.")
    } else {
        print("Es gibt noch offene Aufgaben.")
    }
}

Mehrstufige Entscheidung (else if):

fn bewerte_prioritaet(stufe: Int) -> String {
    match stufe {
        1 => { return "SEHR DRINGEND" }
        2 => { return "NORMAL" }
        3 => { return "NIEDRIG" }
        _ => { return "UNBEKANNT" }
    }
}

fn main() {
    print(bewerte_prioritaet(1))
    print(bewerte_prioritaet(2))
}

Mustervergleich mit match:

fn status_text(code: Int) -> String {
    match code {
        0 => { return "Entwurf" }
        1 => { return "Aktiv" }
        2 => { return "Archiviert" }
        _ => { return "Ungueltig" }
    }
}

fn main() {
    print(status_text(1))
    print(status_text(99))
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. if entscheidet anhand eines Wahrheitswertes (Bool).
  2. match prüft Werte gegen Muster und garantiert Lückenlosigkeit.
  3. Der Wildcard _ fängt alle übrigen Fälle sicher ab.

7. Übungsaufgaben

8. Praxisaufgabe: Status-Logik für den TaskManager

Erstelle für unsere Aufgabenverwaltung die automatische Ampel-Einstufung:

fn berechne_ampel(verbleibende_tage: Int, ist_fertig: Bool) -> String {
    if ist_fertig {
        return "GRUEN: Aufgabe ist abgeschlossen"
    } else {
        if verbleibende_tage < 0 {
            return "ROT: Frist ist abgelaufen!"
        } else {
            if verbleibende_tage <= 2 {
                return "GELB: Bald faellig, bitte bearbeiten"
            } else {
                return "BLAU: Im Zeitplan"
            }
        }
    }
}

fn main() {
    print(berechne_ampel(5, false))
    print(berechne_ampel(1, false))
    print(berechne_ampel(-1, false))
    print(berechne_ampel(-1, true))
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Wann ist ein match einem if / else if vorzuziehen?
  2. Welche Aufgabe erfüllt das _-Muster im match?
  3. Warum verlangt Zelyra, dass bei match alle möglichen Fälle abgedeckt sind?

Kapitel 10: Wiederholungen und Schleifen

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Computer wurden erfunden, um monotone, wiederkehrende Aufgaben fehlerfrei und in Sekundenschnelle zu erledigen – und weil menschliche Entwickler nach der zwanzigsten manuellen Wiederholung unweigerlich Fehler machen oder verzweifeln. Wenn du 1.000 Aufgaben aus einer Datenbank laden, prüfen und anzeigen willst, schreibst du den Code nicht tausendmal, sondern einmal innerhalb einer Schleife. Eine Endlosschleife ist dabei wie ein Hamsterrad mit Turbomotor: Viel Lärm, glühende Lüfter, aber null Fortschritt. Zelyra bietet dafür sichere Konstrukte und erlaubt es sogar, mathematische Garantien über Schleifendurchläufe abzugeben.

3. Verständliche Erklärung

Zelyra kennt drei Arten von Schleifen:

  1. for ... in: Der einfachste und sicherste Weg, um eine Liste von Elementen abzuarbeiten. Die Schleife läuft automatisch über jedes Element und stoppt von selbst:

    fn main() {
    for zahl in [1, 2, 3] {
        print(zahl)
    }
}

  2. while bedingung: Wiederholt den Block so lange, wie die Bedingung wahr (true) bleibt. Ideal, wenn du vorher nicht weißt, wie viele Durchläufe nötig sind.

  3. loop: Eine Dauerschleife. Sie läuft endlos weiter, bis sie im Inneren durch den Befehl break gestoppt wird.

Steuerbefehle:

Schleifeninvariante (invariant): Eine Invariante ist eine Bedingung, die vor, während und nach jedem Schleifendurchlauf wahr sein muss (z. B. invariant { zaehler >= 0 }). Der Zelyra-Verifier (zelyra verify) nutzt Invarianten, um mathematisch zu beweisen, dass die Schleife niemals in unzulässige Zustände gerät!

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: for ... in über ein Array

fn main() {
    aufgaben = ["Planen", "Programmieren", "Testen", "Ausliefern"]
    for a in aufgaben {
        print("Schritt: " + a)
    }
}

Beispiel 2: while mit Zähler und invariant

fn main() {
    mutable zaehler = 1
    while zaehler <= 3
        invariant { zaehler >= 1 }
    {
        print(zaehler)
        zaehler = zaehler + 1
    }
}

Beispiel 3: break und continue gezielt einsetzen

fn main() {
    for zahl in [1, 2, 3, 4, 5] {
        if zahl == 2 {
            # Die 2 wollen wir auslassen:
            continue
        }
        if zahl == 4 {
            # Bei 4 brechen wir komplett ab:
            break
        }
        print(zahl)
    }
}

Ausgabe: Gibt 1 und 3 aus!

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Nutze for ... in für Sammlungen und Arrays.
  2. break beendet die Schleife sofort; continue springt zur nächsten Runde.
  3. Invarianten dokumentieren und beweisen die Sicherheit deiner Schleife.

7. Übungsaufgaben

8. Praxisaufgabe: Aufgaben filtern und zählen

Wir wenden Schleifen auf unsere Aufgabenverwaltung an. Wir zählen die erledigten Aufgaben und geben offene Aufgaben aus:

fn main() {
    aufgaben = ["Konzept schreiben", "Datenbank aufsetzen", "Tests schreiben"]
    mutable erledigt_zaehler = 0

    print("Aufgabenliste durchgehen:")
    for a in aufgaben {
        if a == "Konzept schreiben" {
            print("[X] " + a)
            erledigt_zaehler = erledigt_zaehler + 1
        } else {
            print("[ ] " + a)
        }
    }

    print("Erledigte Aufgaben insgesamt:")
    print(erledigt_zaehler)
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Was ist der Unterschied zwischen break und continue?
  2. Warum ist for ... in bei Arrays sicherer als eine manuelle while-Schleife?
  3. Welche Rolle spielt eine invariant bei der Programmprüfung?

TEIL III – PROGRAMME STRUKTURIEREN

Kapitel 11: Funktionen und Prozeduren

1. Was lerne ich in diesem Kapitel?

In diesem Kapitel lernst du:

2. Warum ist das Thema wichtig?

Wenn du jede Berechnung und jeden Bildschirmausdruck zehnmal an verschiedenen Stellen deines Codes wiederholst, entsteht das gefürchtete „Spaghetti-Phänomen“. Ändert sich eine Geschäftsregel (z. B. wie die Frist einer Aufgabe berechnet wird), müsstest du alle zehn Stellen suchen und anpassen – Fehler sind dabei unausweichlich. Funktionen fassen eine logische Aufgabe unter einem klaren Namen zusammen: Du schreibst sie einmal, testest sie gründlich und verwendest sie beliebig oft.

3. Verständliche Erklärung

Stell dir eine Funktion wie ein Küchengerät vor:

In Zelyra definierst du Funktionen mit dem Schlüsselwort fn:

fn addiere(a: Int, b: Int) -> Int {
    return a + b
}

fn main() {
    print(addiere(2, 3))
}

Besitzt eine Funktion keinen Rückgabewert, weil sie z. B. nur eine Zeile Text ausgibt, ist ihr Rückgabetyp Unit (oder kann weggelassen werden):

fn drucke_trennlinie() {
    print("----------------------------------------")
}

fn main() {
    drucke_trennlinie()
}

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Berechnung mit Rückgabewert

fn berechne_tage_bis_frist(heute_tag: Int, frist_tag: Int) -> Int {
    return frist_tag - heute_tag
}

fn main() {
    tage = berechne_tage_bis_frist(10, 18)
    print(tage)
}

Beispiel 2: Textformatierung in einer Hilfsfunktion

fn format_aufgabe(id_text: String, text: String, fertig: Bool) -> String {
    mutable status_zeichen = "[ ]"
    if fertig {
        status_zeichen = "[X]"
    }
    return status_zeichen + " #" + id_text + ": " + text
}

fn main() {
    ausgabe = format_aufgabe("1", "Dokumentation lesen", true)
    print(ausgabe)
}

Beispiel 3: Prozedur zur Menüausgabe

fn zeige_kopfzeile(benutzer: String) {
    print("Angemeldet als: " + benutzer)
    print("========================================")
}

fn main() {
    zeige_kopfzeile("Sabine")
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Eine Funktion sollte genau eine einzige, klar benannte Aufgabe erfüllen.
  2. Reine Funktionen erzeugen bei gleichen Eingaben immer die gleichen Ausgaben und haben keine Seiteneffekte.
  3. Namen von Funktionen sollten aussagekräftige Verben sein (z. B. berechne_differenz, format_aufgabe).

7. Übungsaufgaben

8. Praxisaufgabe: Aufgabenanzeige modularisieren

Schreibe ein Zelyra-Programm, das drei Aufgaben mit ID-Text, Name und Erledigungsstatus über eine wiederverwendbare Formatierungsfunktion aufbereitet und ausgibt:

fn format_eintrag(id_text: String, name: String, erledigt: Bool) -> String {
    mutable symbol = "[OFFEN]"
    if erledigt {
        symbol = "[OK]"
    }
    return symbol + " Aufgabe " + id_text + ": " + name
}

fn main() {
    print(format_eintrag("1", "Post abholen", true))
    print(format_eintrag("2", "Rechnung bezahlen", false))
    print(format_eintrag("3", "Backup erstellen", false))
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welchen Typ besitzt eine Funktion, die keinen Wert zurückgibt?
  2. Warum sind reine Funktionen einfacher zu testen als Funktionen mit globalen Seiteneffekten?
  3. Was prüft der Zelyra-Compiler bei jedem Funktionsaufruf?

Kapitel 12: Verträge und Vorbedingungen (Design by Contract)

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Häufig entstehen Fehler, weil Entwickler Annahmen treffen, die nirgendwo festgeschrieben sind: »Diese Funktion darf niemals mit einer negativen Zahl aufgerufen werden!« Wenn jemand die Funktion ein halbes Jahr später doch mit -1 aufruft, kracht es unerwartet im Gebälk. In herkömmlichen Sprachen schreibt man seitenlange if-Prüfungen oder hofft auf das Prinzip Hoffnung. Verträge (requires und ensures) machen Schluss mit dem Hoffen. Sie sind wie ein notarieller Vertrag an der Funktionsgrenze: »Lieferst du mir gültige Daten (requires), garantiere ich dir ein korrektes Ergebnis (ensures). Wenn nicht, weise ich den Aufruf sofort ab!« Wer einmal erlebt hat, wie Buchhalter nachts rotieren, weil fehlerhafte Buchungsbeträge das Hauptbuch zerschossen haben, liebt vertragsbasierte Programmierung.

3. Verständliche Erklärung

Ein Vertrag in Zelyra funktioniert wie ein notarieller Vertrag zwischen dem Aufrufer und der Funktion:

Wird ein Vertrag verletzt, stoppt Zelyra sofort mit einem präzisen Fehler (E-CONTRACT-*) und zeigt genau, wer den Vertrag gebrochen hat.

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Vorbedingung mit requires

fn dividiere(zaehler: Int, nenner: Int) -> Int
    requires { nenner != 0 }
{
    return zaehler / nenner
}

fn main() {
    ergebnis = dividiere(100, 4)
    print(ergebnis)
}

Beispiel 2: Vor- und Nachbedingung kombiniert

fn prioritaet_anpassen(aktuelle_stufe: Int, delta: Int) -> Int
    requires { aktuelle_stufe >= 1 && delta >= 0 }
    ensures { result >= 1 }
{
    neue_stufe = aktuelle_stufe + delta
    return neue_stufe
}

fn main() {
    p = prioritaet_anpassen(2, 1)
    print(p)
}

Beispiel 3: Schleifeninvariante

fn zaehle_bis(grenze: Int) -> Int
    requires { grenze >= 0 }
    ensures { result == grenze }
{
    mutable i = 0
    while i < grenze
        invariant { i >= 0 }
    {
        i = i + 1
    }
    return i
}

fn main() {
    print(zaehle_bis(5))
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. requires schützt die Funktion vor unzulässigen Eingaben des Aufrufers.
  2. ensures garantiert dem Aufrufer ein korrektes Ergebnis über result.
  3. Verträge machen implizite Annahmen zu überprüfbaren, lebendigen Spezifikationen.

7. Übungsaufgaben

8. Praxisaufgabe: Fortschrittsrechner für Aufgaben

Schreibe eine abgesicherte Funktion für die Aufgabenverwaltung:

fn berechne_fortschritt(erledigt: Int, gesamt: Int) -> Int
    requires { gesamt > 0 && erledigt >= 0 && erledigt <= gesamt }
    ensures { result >= 0 && result <= 100 }
{
    return (erledigt * 100) / gesamt
}

fn main() {
    quote = berechne_fortschritt(3, 4)
    print(quote)
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Wann wird eine requires-Bedingung geprüft: vor oder nach der Ausführung?
  2. Worauf bezieht sich das Wort result in einem Vertrag?
  3. Warum ersetzt ein Vertrag kein HTML-Formularvalidierungs-Muster?

Kapitel 13: Sammlungen, Listen und Wörterbücher (Arrays & Maps)

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Eine Anwendung, die nur einzelne Werte speichern kann, wäre nutzlos. In der Praxis arbeiten wir fast immer mit Sammlungen: Listen von Aufgaben, E-Mail-Adressen oder Tabellenzeilen aus einer Datenbank. Manchmal suchen wir Elemente nach ihrer Reihenfolge (Listen bzw. Arrays). Sehr oft wollen wir Daten jedoch direkt über einen eindeutigen Schlüssel nachschlagen – zum Beispiel die Benutzereinstellungen zu einer User-ID, ein Wörterbuch von Übersetzungstexten oder Ländervorwahlen. Dafür bietet Zelyra typisierte Wörterbücher (Map).

3. Verständliche Erklärung

Teil A: Arrays – Die geordnete Liste

Ein Array ist wie ein Setzkasten: Jedes Fach hat eine feste Nummer (Index) und enthält genau ein Element. In Zelyra müssen alle Elemente im selben Kasten denselben Typ haben (Int[], String[] etc.):

fn main() {
    zahlen: Int[] = [10, 20, 30, 40]
    print(len(zahlen))
}

Zelyra stellt mächtige Hilfswerkzeuge für Arrays bereit:

Teil B: Maps – Assoziative Schlüssel-Wert-Wörterbücher

Eine Map ordnet jedem eindeutigen Schlüssel (Key) genau einen Wert (Value) zu.

fn main() {
    vorwahlen: Map<String, Int> = Map {
        "de": 49
        "at": 43
        "ch": 41
    }
}

Die wichtigsten Operationen auf Maps:

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Array anlegen und mit for-Schleife durchlaufen

fn main() {
    aufgabe_ids: Int[] = [101, 102, 103, 104]
    for id in aufgabe_ids {
        print(id)
    }
}

Beispiel 2: Elemente an ein Array anfügen

fn main() {
    mutable liste: Int[] = [1, 2, 3]
    liste = append(liste, 4)
    print(len(liste))
}

Beispiel 3: Wörterbuch (Map) anlegen, aktualisieren und abfragen

fn main() {
    preise: Map<String, Int> = Map {
        "Kaffee": 3
        "Tee": 2
    }
    
    # Neues Element hinzufügen
    mutable aktion = put(preise, "Kuchen", 4)
    # Vorhandenen Preis anpassen
    aktion = put(aktion, "Kaffee", 4)
    
    # Nullsicher mit match abfragen
    match get(aktion, "Kaffee") {
        Some(preis) => {
            print("Kaffeepreis in Euro:")
            print(preis)
        }
        None => {
            print("Artikel nicht gefunden.")
        }
    }
    
    # Alle Schlüssel und Werte ausgeben
    print(keys(aktion))
}

Beispiel 4: Prüfen der Existenz in einer Map

fn main() {
    einstellungen: Map<String, Bool> = Map {
        "dunkelmodus": true
        "benachrichtigungen": false
    }
    
    if contains(einstellungen, "dunkelmodus") {
        print("Dunkelmodus-Einstellung ist konfiguriert.")
    }
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Arrays in Zelyra sind typrein: Int[], String[], Bool[].
  2. Das Durchlaufen von Arrays erfolgt elegant und sicher mit for element in sammlung { ... }.
  3. Map<Key, Value> speichert eindeutige Schlüssel-Wert-Paare.
  4. get(map, key) liefert immer eine Option (Some oder None) und schützt vor Laufzeitabstürzen.
  5. put(map, key, value) liefert funktional ein neues, aktualisiertes Wörterbuch.

7. Übungsaufgaben

8. Praxisaufgabe: Aufgaben-Prioritäten nachschlagen

Erstelle eine Verwaltung von Prioritätsstufen für Aufgaben mit einer Map:

fn prioritaet_anzeigen(prioritaeten: Map<String, Int>, aufgabe: String) {
    match get(prioritaeten, aufgabe) {
        Some(stufe) => {
            print("Prioritaet fuer " + aufgabe + ":")
            print(stufe)
        }
        None => {
            print("Keine Prioritaet hinterlegt fuer: " + aufgabe)
        }
    }
}

fn main() {
    prio_map: Map<String, Int> = Map {
        "Datenbankmigration": 1
        "CSS anpassen": 3
        "Dokumentation": 2
    }
    
    prioritaet_anzeigen(prio_map, "Datenbankmigration")
    prioritaet_anzeigen(prio_map, "Kaffeepause")
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welchen Typ hat der Ausdruck ["A", "B", "C"]?
  2. Warum schlägt append([1, 2], "Drei") beim Kompilieren fehl?
  3. Wie prüfst du effizient, ob ein Wert in einer Liste existiert?

Kapitel 14: Eigene Datentypen erstellen (Records & Tables)

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

In schlechter Software wird fast alles als einfache Zahl oder Zeichenkette behandelt („Primitive Obsession“). Wenn eine Funktion pruefe(benutzer_id: Int, aufgabe_id: Int) erwartet, du aber versehentlich die IDs vertauschst, merkt der Computer bei einfachen Int-Typen gar nichts – die Software bucht womöglich fatale Daten falsch zu. Mit eigenen Typen unterscheidet Zelyra schon beim Kompilieren zwischen einer UserId und einer TaskId.

3. Verständliche Erklärung

Eigene Datentypen erlauben es dir, der realen Welt einen Namen zu geben:

  1. Fachliche Typ-Aliase:

    type TaskId = Id

fn main() {
    print("Typalias TaskId aktiv")
}

    Der Alias gibt der ID einen fachlichen Namen. Er besitzt keine eigene Runtimeidentität; verwechslungssichere Geschäftsregeln müssen im konkreten Prüfumfang abgesichert werden.

  2. Aufzählungs- und Summentypen:

    Ein Aufzählungstyp beschreibt einen Wert, der genau eine Variante aus einer festen Menge benannter Varianten annimmt. Eine Variante kann zusätzlich einen Wert tragen; deshalb heißen solche Typen auch Summentypen. Das allgemeine Konzept lässt sich als enum State { Draft, Active, Archived } skizzieren. Diese Schreibweise ist jedoch nur eine Konzeptdarstellung und keine unterstützte Zelyra-Syntax. Benutzerdefinierte enum-Deklarationen gehören nicht zum derzeit dokumentierten Sprachumfang. Eingebaute Summentypen sind Option<T> und Result<T, E>; ihre Varianten werden mit match behandelt.

  3. Tabellen als strukturierte Datentypen:

    table aufgaben {
    id: Id primary auto
    beschreibung: String required
    fertig: Bool
}

fn main() {
    print("Tabellenschema definiert")
}

    Dieses Schema definiert nicht nur eine Datenbanktabelle, sondern stellt in Zelyra automatisch den Datentyp für eine Aufgabe bereit!

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Eigene Typnamen für IDs

type TaskId = Id

fn main() {
    print("Typalias erfolgreich definiert")
}

Beispiel 2: Ein Datenmodell als Tabelle definieren

table aufgaben {
    id: Id primary auto
    beschreibung: String required
    erledigt: Bool
}

fn main() {
    print("Tabellenschema fuer Aufgaben definiert")
}

Beispiel 3: Typisierte Attribute in Funktionen ansprechen

table projekte {
    id: Id primary auto
    name: String required
    aktiv: Bool
}

fn zeige_projekt_status(p_name: String, p_aktiv: Bool) {
    mutable status = "Pausiert"
    if p_aktiv {
        status = "Aktiv"
    }
    print("Projekt: " + p_name + " [" + status + "]")
}

fn main() {
    zeige_projekt_status("Web-Portal", true)
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Eigene Datentypen spiegeln die Geschäftswelt wider und verhindern fatale Parameterverwechslungen.
  2. table-Definitionen sind in Zelyra gleichzeitig Datenbankschema und Sprach-Datentyp.
  3. Reservierte Wörter (title, list, etc.) dürfen nicht als Spalten- oder Variablennamen genutzt werden.

7. Übungsaufgaben

8. Praxisaufgabe: Das Kernschema der Aufgabenverwaltung

Definiere das vollständige Zelyra-Schema für unsere Aufgabenverwaltung:

table aufgaben {
    id: Id primary auto
    name: String required
    beschreibung: String
    prioritaet: Int
    ist_erledigt: Bool
}

fn main() {
    print("Kernschema der Aufgabenverwaltung aktiv.")
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welchen Vorteil bietet type TaskId = Id gegenüber einem einfachen Int?
  2. Warum müssen Tabellenfelder in Zelyra stets einen festen Typ besitzen?
  3. Welche Namen sollten als Feldbezeichnungen vermieden werden?

Kapitel 15: Module und Code-Organisation

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Zu Beginn schreibt man gerne alles in eine einzige Datei. Doch wenn deine Aufgabenverwaltung wächst – mit Datenbanktabellen, 20 Funktionen, Webformularen und Validierungen –, verliert man in einer 2000-Zeilen-Datei schnell den Überblick. Gute Softwareentwicklung bedeutet, Code so zu organisieren, dass man Neuerungen sofort an der richtigen Stelle findet.

3. Verständliche Erklärung

Ein professionelles Zelyra-Projekt folgt einer klaren Ablagestruktur:

[package]
name = "aufgaben_planer"
version = "0.1.0"
authors = ["Entwickler <dev@example.com>"]

[capabilities]
filesystem = false
database = true

Hinweis zur Sprachkompatibilität: Zelyra unterstützt ausdrückliche projektrelative Importe wie import "src/models.zyl" as models. Diese Importe verbinden Quelldateien innerhalb eines Projekts; sie bieten weder eine Paketregistrierung noch dynamische Laufzeitimporte. Modulgraph und Deployment-Abschluss bleiben experimentell und können unvollständig sein. Die Sprachkompatibilitätslinie bleibt 0.1.

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Eine saubere Hauptdatei

fn main() {
    print("Zelyra Aufgaben-System bereit.")
}

Beispiel 2: Trennung von Logikfunktionen

fn format_system_status(status: String) -> String {
    return "[STATUS] " + status
}

fn main() {
    print(format_system_status("Datenbank verbunden"))
}

Beispiel 3: Deklaration von Capabilities in der Projektdatei In zelyra.toml legst du fest, welche Systemzugriffe das Projekt überhaupt anfordern darf. Greift dein Code auf die Datenbank zu, muss database = true aktiviert sein.

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. zelyra.toml steuert Metadaten und Sicherheitsrichtlinien des Projekts.
  2. Trenne Datenmodell (table), Geschäftslogik (fn) und Darstellung sauber voneinander.
  3. Ordnung im Projektverzeichnis schützt vor Flüchtigkeitsfehlern im Team.

7. Übungsaufgaben

8. Praxisaufgabe: Projektstruktur für die Aufgabenverwaltung

Lege die Struktur fest mit folgendem Inhalt in main.zyl:

table aufgaben {
    id: Id primary auto
    name: String required
    erledigt: Bool
}

fn starte_system() {
    print("========================================")
    print("   AUFGABEN-MANAGER ERFOLGREICH GESTARTET")
    print("========================================")
}

fn main() {
    starte_system()
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welche Datei enthält die Metadaten eines Zelyra-Projekts?
  2. Warum ist die Trennung von Datenmodell und Ausführungslogik sinnvoll?
  3. Wie prüft die Zelyra-CLI das gesamte Projekt auf einmal?

TEIL IV – SICHERHEIT UND FEHLERBEHANDLUNG

Kapitel 16: Fehlerarten und ihre Ursachen

1. Was lerne ich in diesem Kapitel?

In diesem Kapitel lernst du:

2. Warum ist das Thema wichtig?

Fehler sind beim Programmieren völlig normal. Selbst erfahrene Programmierer machen dutzende Fehler pro Tag – der einzige Unterschied ist, dass Profis dabei etwas entspannter Kaffee trinken. Der Unterschied zwischen frustrierenden und erfolgreichen Entwicklern liegt nicht darin, keine Fehler zu machen, sondern darin, Fehlermeldungen lesen und verstehen zu können. Zelyra wurde so entworfen, dass möglichst viele Fehler bereits beim Kompilieren (zelyra check) abgefangen werden, bevor die Anwendung den ersten Nutzer erreicht und dein Bereitschaftshandy am Wochenende klingelt.

3. Verständliche Erklärung

Wir unterscheiden vier Kategorien:

  1. Syntaxfehler (E-LEX-*, E-PARSE-*): Du hast die Grammatik der Sprache verletzt – wie ein Rechtschreibfehler in einem Diktat (z. B. eine geschlossene Klammer vergessen).
  2. Typfehler (E-TYPE-*): Die Grammatik stimmt, aber die Bedeutung passt nicht zusammen (z. B. Text zu einer Zahl addieren).
  3. Vertrags- und Berechtigungsfehler (E-CONTRACT-*, E-CAP-*): Eine vereinbarte Vorbedingung wurde verletzt oder eine Funktion versucht, ohne Erlaubnis auf das Dateisystem zuzugreifen.
  4. Logikfehler: Das Programm läuft fehlerfrei durch, tut aber nicht das, was du beabsichtigt hast (z. B. Rabatt addiert statt abgezogen).

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Typischer Syntaxfehler (und wie man ihn liest) Wenn du in Zelyra eine Klammer vergisst:

# Syntaktisch korrekt:
fn korrekte_klammern() {
    print("Alle Klammern sind geschlossen.")
}

fn main() {
    korrekte_klammern()
}

Beispiel 2: Berechtigungsfehler (Capability-Prüfung) Versucht eine Funktion ohne deklarierte Rechte auf Systemressourcen zuzugreifen, stoppt Zelyra sofort:

fn lese_datei(pfad: String) -> String
    uses FileSystem
{
    return read_text(pfad)
}

fn main() {
    print("Dateizugriff sauber deklariert.")
}

Beispiel 3: Logikfehler durch Verträge entlarven

fn berechne_rabattpreis(original: Int, rabatt: Int) -> Int
    requires { original >= 0 && rabatt >= 0 && rabatt <= original }
    ensures { result <= original }
{
    return original - rabatt
}

fn main() {
    preis = berechne_rabattpreis(100, 20)
    print(preis)
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Ein Compilerfehler ist kein Scheitern, sondern ein wertvoller Hinweis.
  2. Je früher ein Fehler gefunden wird (Compile-Zeit statt Laufzeit), desto sicherer ist die Software.
  3. Verträge (requires, ensures) verwandeln tückische Logikfehler in sofort sichtbare Vertragsbrüche.

7. Übungsaufgaben

8. Praxisaufgabe: Fehlertolerante Aufgabendauer-Berechnung

Schreibe eine Funktion für die Aufgabenverwaltung, die verhindert, dass negative Stunden erfasst werden:

fn erfasse_stunden(bisherige_stunden: Int, neue_stunden: Int) -> Int
    requires { bisherige_stunden >= 0 && neue_stunden >= 0 }
    ensures { result >= bisherige_stunden }
{
    return bisherige_stunden + neue_stunden
}

fn main() {
    gesamt = erfasse_stunden(5, 3)
    print(gesamt)
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welche Fehlermeldung (E-...) erzeugt ein vergessenes Schlüsselwort?
  2. Warum kann ein Programm trotz fehlerfreier Kompilierung falsch rechnen?
  3. Wie helfen Verträge beim Aufspüren logischer Denkfehler?

Kapitel 17: Fehler als Werte – Das Result-Muster

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

In vielen älteren Sprachen (wie Java oder Python) wirft eine Funktion im Fehlerfall eine »Exception«. Exceptions sind wie Feueralarme: Oft laut, panisch, und niemand weiß genau, wer den Notausgang blockiert hat. Wenn irgendwo im Code eine solche Ausnahme vergessen wird, stürzt die gesamte Webanwendung mit einem Serverfehler ab. In Zelyra gibt es keine unkontrollierten Abstürze: Wenn eine Operation fehlschlagen kann (z. B. Datei nicht gefunden oder ungültige ID), gibt sie zwingend ein Result<T, E> zurück. Der Compiler zwingt dich, beide Fälle zu behandeln – Gelassenheit statt Panik.

3. Verständliche Erklärung

Stelle dir ein Postpaket vor:

Ein Paket kann niemals „explodieren“ – du musst es einfach nur annehmen und nachsehen:

fn dividiere_sicher(a: Int, b: Int) -> Result<Int, String> {
    if b == 0 {
        return Err("Division durch 0 nicht erlaubt")
    }
    return Ok(a / b)
}

fn main() {
    print("Sichere Division definiert.")
}

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Eine Funktion mit Result definieren

fn pruefe_prioritaet(stufe: Int) -> Result<Int, String> {
    if stufe < 1 {
        return Err("Prioritaet zu niedrig (mindestens 1)")
    }
    if stufe > 3 {
        return Err("Prioritaet zu hoch (maximal 3)")
    }
    return Ok(stufe)
}

fn main() {
    res = pruefe_prioritaet(2)
    match res {
        Ok(stufe) => {
            print("Gueltige Prioritaet:")
            print(stufe)
        }
        Err(fehler) => {
            print(fehler)
        }
    }
}

Beispiel 2: Fehlerfall behandeln

fn hole_kontostand(pin: Int) -> Result<Int, String> {
    if pin != 1234 {
        return Err("Falsche PIN!")
    }
    return Ok(500)
}

fn main() {
    versuch = hole_kontostand(9999)
    match versuch {
        Ok(betrag) => {
            print(betrag)
        }
        Err(meldung) => {
            print("Abgewiesen: " + meldung)
        }
    }
}

Beispiel 3: Sichere Werteumwandlung

fn pruefe_titel_laenge(titel: String) -> Result<String, String> {
    if titel == "" {
        return Err("Aufgabentitel darf nicht leer sein.")
    }
    return Ok(titel)
}

fn main() {
    ergebnis = pruefe_titel_laenge("Projektbericht")
    match ergebnis {
        Ok(t) => {
            print("Gueltiger Titel: " + t)
        }
        Err(e) => {
            print("Fehler: " + e)
        }
    }
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Result<T, E> macht Fehler zu regulären Rückgabewerten.
  2. Ok(v) repräsentiert Erfolg, Err(e) den begründeten Fehlschlag.
  3. Mit match müssen immer beide Ausgänge behandelt werden – das schützt vor Abstürzen.

7. Übungsaufgaben

8. Praxisaufgabe: Validierung beim Anlegen einer neuen Aufgabe

Erstelle eine sichere Validierungsfunktion für neue Aufgaben:

fn erstelle_aufgabe_geprueft(name: String, prioritaet: Int) -> Result<String, String> {
    if name == "" {
        return Err("Name darf nicht leer sein!")
    }
    if prioritaet < 1 {
        return Err("Prioritaet muss mindestens 1 sein!")
    }
    return Ok("Aufgabe [" + name + "] erfolgreich angelegt.")
}

fn main() {
    treffer1 = erstelle_aufgabe_geprueft("Dokumentation fertigstellen", 1)
    match treffer1 {
        Ok(msg) => {
            print(msg)
        }
        Err(err) => {
            print("Fehler: " + err)
        }
    }

    treffer2 = erstelle_aufgabe_geprueft("", 0)
    match treffer2 {
        Ok(msg) => {
            print(msg)
        }
        Err(err) => {
            print("Fehler: " + err)
        }
    }
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Wofür steht T und wofür steht E im Typ Result<T, E>?
  2. Warum führt ein unbehandelter Fehler in Zelyra nicht zum plötzlichen Programmabsturz?
  3. Wie verarbeitet man den Inhalt eines Result sicher?

Kapitel 18: Das Nichts existiert nicht – Der sichere Umgang mit Option

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

In Sprachen wie JavaScript, Java, PHP oder C existiert null. Wenn ein Programm versucht, eine Methode auf einem null-Wert aufzurufen, stürzt es augenblicklich mit einer gefürchteten NullPointerException oder Cannot read properties of null ab. Sir Tony Hoare nannte seine Erfindung von null rückblickend selbst seinen »Milliarden-Dollar-Fehler«. Zelyra besitzt schlicht kein null. Wir haben null gar nicht erst zur Party eingeladen! Jeder Wert ist garantiert vorhanden. Wenn etwas fehlen kann, muss es ausdrücklich als Option deklariert werden – und der Compiler passt auf, dass du keinen None-Fall übersiehst.

3. Verständliche Erklärung

Stell dir eine Schachtel vor:

Du kannst nicht versehentlich in ein „Nichts“ greifen, weil du die Schachtel erst mit match öffnen musst:

fn finde_aufgabe_nach_id(id: Int) -> Option<String> {
    if id == 42 {
        return Some("Server aufsetzen")
    }
    return None
}

fn main() {
    print("Aufgabensuche definiert.")
}

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Option erzeugen und auswerten

fn main() {
    treffer: Option<String> = Some("Zelyra 0.1 Handbuch")
    match treffer {
        Some(titel) => {
            print("Gefunden: " + titel)
        }
        None => {
            print("Kein Treffer vorhanden")
        }
    }
}

Beispiel 2: first() und last() auf Listen Greifst du auf eine leere Liste zu, stürzt Zelyra nicht ab – es liefert None:

fn main() {
    meine_liste: Int[] = [100, 200, 300]
    erstes_element = first(meine_liste)
    match erstes_element {
        Some(wert) => {
            print("Erster Wert:")
            print(wert)
        }
        None => {
            print("Die Liste ist leer!")
        }
    }
}

Beispiel 3: Standardwert bereitstellen mit Option

fn aufgabe_titel_oder_standard(opt_titel: Option<String>) -> String {
    match opt_titel {
        Some(t) => {
            return t
        }
        None => {
            return "Ohne Titel"
        }
    }
}

fn main() {
    print(aufgabe_titel_oder_standard(Some("Wichtiges Meeting")))
    print(aufgabe_titel_oder_standard(None))
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. In Zelyra gibt es kein null und keinen NullPointerException-Absturz.
  2. Wenn ein Wert fehlen kann, heißt der Typ Option<T> oder T?.
  3. Some(x) verpackt den Wert, None signalisiert das Fehlen.

7. Übungsaufgaben

8. Praxisaufgabe: Aufgabendetails sicher abfragen

Implementiere die Nachschlagefunktion für unsere Aufgabenverwaltung:

fn suche_aufgabe_beschreibung(id: Int) -> Option<String> {
    if id == 1 {
        return Some("Datenbankschema fuer Zelyra anlegen")
    }
    if id == 2 {
        return Some("Weboberflaeche gestalten")
    }
    return None
}

fn main() {
    suche1 = suche_aufgabe_beschreibung(1)
    match suche1 {
        Some(text) => {
            print("Aufgabe 1: " + text)
        }
        None => {
            print("Aufgabe 1 nicht gefunden!")
        }
    }

    suche99 = suche_aufgabe_beschreibung(99)
    match suche99 {
        Some(text) => {
            print("Aufgabe 99: " + text)
        }
        None => {
            print("Aufgabe 99 nicht gefunden!")
        }
    }
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Warum gibt es in Zelyra kein null?
  2. Was ist der Unterschied zwischen String und Option<String>?
  3. Welche zwei Muster werden in einem match über eine Option immer abgefragt?

Kapitel 19: Tests und Qualitätssicherung

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Manuelle Tests (Klicken im Browser oder wiederholtes manuelles Aufrufen) sind mühsam, fehleranfällig und unvollständig. Sobald eine Software komplexer wird, führt jede kleine Änderung an einer Stelle unweigerlich zu neuen Fehlern an einer anderen Stelle („Regressionen“). Automatisierte Tests stellen sicher, dass alle bereits gebauten Funktionen auch nach Wochen und Monaten noch exakt wie vereinbart arbeiten.

3. Verständliche Erklärung

Testen in Zelyra stützt sich auf zwei kraftvolle Säulen:

  1. Formale Vertragsverifikation mit zelyra verify: Der Compiler prüft, ob die Vor- und Nachbedingungen (requires, ensures) deiner Funktionen mathematisch und logisch haltbar sind.
  2. Prüffunktionen mit Erwartungsabgleich: Testfunktionen übergeben Geschäftslogik-Beispielen Eingaben und vergleichen tatsächliche mit erwarteten Ergebnissen. Die eingebaute Assertion assert(bedingung, meldung) meldet einen Fehler, wenn die Bedingung falsch ist.

Die aktuelle CLI-Referenz führt keinen Unterbefehl zelyra test auf. Lege projektbezogene Testroutinen in einer ausführbaren .zyl-Datei ab und starte sie mit zelyra run <file.zyl>. Prüfe den Quelltext vor der Ausführung mit zelyra check; zelyra verify führt die unterstützten formalen Vertragsprüfungen aus.

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Eine direkte Assertion

fn main() {
    ergebnis = 6 * 7
    assert(ergebnis == 42, "Die Multiplikation muss 42 ergeben")
}

Beispiel 2: Eine einfache Prüffunktion

fn pruefe(test_name: String, bedingung: Bool) {
    if bedingung {
        print("[PASS] " + test_name)
    } else {
        print("[FAIL] " + test_name)
    }
}

fn verdopple(x: Int) -> Int {
    return x * 2
}

fn main() {
    pruefe("Verdopple 5 ergibt 10", verdopple(5) == 10)
    pruefe("Verdopple 0 ergibt 0", verdopple(0) == 0)
}

Beispiel 3: Testen von Option-Rückgaben

fn ist_volljaehrig(alter: Int) -> Option<Bool> {
    if alter < 0 {
        return None
    }
    return Some(alter >= 18)
}

fn main() {
    test1 = ist_volljaehrig(20)
    match test1 {
        Some(ok) => {
            if ok {
                print("[PASS] 20 Jahre ist volljaehrig")
            } else {
                print("[FAIL] Unerwarteter Zustand")
            }
        }
        None => {
            print("[FAIL] Alter ungueltig")
        }
    }
}

Beispiel 4: Verifikation mit Verträgen absichern

fn berechne_ueberstunden(stunden: Int, regelarbeitszeit: Int) -> Int
    requires { stunden >= 0 && regelarbeitszeit >= 0 }
    ensures { result >= 0 }
{
    if stunden > regelarbeitszeit {
        return stunden - regelarbeitszeit
    }
    return 0
}

fn main() {
    print(berechne_ueberstunden(45, 40))
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Ungesteter Code ist kaputter Code, von dem du es nur noch nicht weißt.
  2. zelyra verify prüft Funktionsverträge direkt auf Sprachebene.
  3. Schreibe Tests, die Randbedingungen und Fehlerpfade gezielt herausfordern.

7. Übungsaufgaben

8. Praxisaufgabe: Test-Runner für die Aufgaben-Geschäftslogik

Baue eine kleine Test-Suite für die Kernlogik der Aufgabenverwaltung:

fn test_fall(beschreibung: String, ok: Bool) {
    if ok {
        print("OK: " + beschreibung)
    } else {
        print("FEHLER: " + beschreibung)
    }
}

fn filter_prioritaet(p: Int) -> Bool {
    return p == 1
}

fn main() {
    print("Starte Test-Suite: Aufgabenlogik")
    test_fall("Prioritaet 1 wird gefiltert", filter_prioritaet(1) == true)
    test_fall("Prioritaet 2 wird ignoriert", filter_prioritaet(2) == false)
    print("Test-Suite abgeschlossen.")
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Was versteht man unter einer „Regression“ in der Softwareentwicklung?
  2. Welche Aufgabe übernimmt der CLI-Befehl zelyra verify?
  3. Warum sind Grenzwerte (z. B. 0 oder maximale Kapazität) besonders testrelevant?

TEIL V – PRAKTISCHE DATENVERARBEITUNG

Kapitel 20: Arbeiten mit Dateien

1. Was lerne ich in diesem Kapitel?

In diesem Kapitel lernst du:

2. Warum ist das Thema wichtig?

Variablen im Arbeitsspeicher gehen verloren, sobald ein Programm beendet wird oder der Rechner neu startet. Um Daten dauerhaft zu sichern – z. B. Exporte, Konfigurationsdateien oder Protokolle –, müssen sie auf die Festplatte geschrieben werden. Gleichzeitig stellen Dateizugriffe ein Sicherheitsrisiko dar. Zelyra schützt das System, indem Funktionen ihre Zugriffsrechte explizit deklarieren müssen.

3. Verständliche Erklärung

Stell dir das Dateisystem wie ein Archiv vor:

fn speichere_notiz(pfad: String, inhalt: String)
    uses FileSystem
{
    write_text(pfad, inhalt)
}

fn main() uses FileSystem {
    speichere_notiz("notiz.txt", "Einkaufsliste: Milch, Brot")
    print("Notiz gespeichert.")
}

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Text schreiben und lesen

fn datei_workflow() uses FileSystem {
    pfad = "aufgaben_export.txt"
    write_text(pfad, "Aufgabe 1: Zelyra lernen")
    text = read_text(pfad)
    print("Gelesener Inhalt: " + text)
}

fn main() uses FileSystem {
    datei_workflow()
}

Beispiel 2: Datei aufräumen mit delete_file

fn aufraeumen(pfad: String) uses FileSystem {
    delete_file(pfad)
    print("Datei geloescht.")
}

fn main() uses FileSystem {
    write_text("temp.txt", "Kurzlebig")
    aufraeumen("temp.txt")
}

Beispiel 3: Verzeichnisinhalte auflisten

fn zeige_dateien(ordner: String) uses FileSystem {
    dateien = list_dir(ordner)
    for datei in dateien {
        print("Gefundene Datei: " + datei)
    }
}

fn main() uses FileSystem {
    zeige_dateien(".")
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Jede Funktion, die Dateien berührt, muss uses FileSystem deklarieren.
  2. write_text legt Dateien an oder überschreibt sie vollständig.
  3. read_text liefert den gesamten Dateiinhalt als String.

7. Übungsaufgaben

8. Praxisaufgabe: Aufgabenliste in eine Textdatei exportieren

Speichere die offenen Aufgaben unserer Anwendung als Datei:

fn exportiere_aufgaben(pfad: String) uses FileSystem {
    inhalt = "[ ] Dokumentation fertigstellen\n[OK] Zelyra-Compiler installieren\n[ ] Backup konfigurieren"
    write_text(pfad, inhalt)
    print("Aufgaben erfolgreich nach " + pfad + " exportiert.")
}

fn main() uses FileSystem {
    exportiere_aufgaben("aufgaben_heute.txt")
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welche Fähigkeit muss eine Funktion anfordern, um write_text aufzurufen?
  2. Warum verlangt Zelyra uses FileSystem auch für main()?
  3. Welche Funktion liefert eine Liste aller Dateinamen in einem Ordner?

Kapitel 21: Datum, Uhrzeit, Zufall und strukturierte Daten

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Praktisch jede reale Software benötigt Zeitangaben: Wann wurde eine Aufgabe erstellt? Wann ist die Frist abgelaufen? Zeitzonen, Sommerzeit-Umstellungen und Schaltsekunden haben allerdings schon gestandene Mathematiker zum Weinen gebracht. Auch strukturierte Datenformate wie JSON sind im Internet Standard – von REST-APIs bis hin zu Speicherständen. Zelyra integriert Zeit (uses Clock), Zufall (uses Random) und JSON nahtlos, typgeprüft und deterministisch testbar.

3. Verständliche Erklärung

fn zeige_zeit() uses Clock {
    jetzt = now()
    print("Aktuelle Systemzeit erfasst")
}

fn main() uses Clock {
    zeige_zeit()
}

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Fristen und Zeitmessung mit Clock

fn protokolliere_erstellung(aufgabe: String) uses Clock {
    erstellt_um = now()
    print("Aufgabe angelegt: " + aufgabe)
}

fn main() uses Clock {
    protokolliere_erstellung("Server patchen")
}

Beispiel 2: Zufällige Ticket-Nummern erzeugen

fn generiere_ticket_nummer() -> Int uses Random {
    return random_int(1000, 9999)
}

fn main() uses Random {
    ticket = generiere_ticket_nummer()
    print("Dein Ticket-Code:")
    print(ticket)
}

Beispiel 3: Daten als JSON exportieren

fn exportiere_ids_als_json(ids: Int[]) -> String {
    return json_encode(ids)
}

fn main() {
    ids: Int[] = [101, 102, 103]
    json_text = exportiere_ids_als_json(ids)
    print("JSON-Ausgabe: " + json_text)
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. now() liefert die aktuelle Zeit und erfordert uses Clock.
  2. random_int erzeugt Zufallszahlen und verlangt uses Random.
  3. json_encode wandelt Zelyra-Datenstrukturen in standardisierten JSON-Text um.

7. Übungsaufgaben

8. Praxisaufgabe: Aufgaben-Snapshot als JSON sichern

Erstelle einen JSON-Snapshot der Aufgaben-IDs und sichere ihn als Datei:

fn sichere_snapshot(dateiname: String, ids: Int[])
    uses Clock, FileSystem
{
    json_daten = json_encode(ids)
    write_text(dateiname, json_daten)
    print("Snapshot erfolgreich gesichert.")
}

fn main() uses Clock, FileSystem {
    aktuelle_ids: Int[] = [1, 2, 5, 8]
    sichere_snapshot("aufgaben_snapshot.json", aktuelle_ids)
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welche Capability benötigt eine Funktion, die now() aufruft?
  2. Warum verlangt Zelyra für Zufallszahlen die Berechtigung uses Random?
  3. In welches Format wandelt json_encode Zelyra-Objekte um?

Kapitel 22: Nebenläufigkeit und Hintergrundaufgaben

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Moderne Computer und Server besitzen viele Rechenkerne. Wenn ein Programm drei unabhängige Berichte erstellen oder zwei APIs im Netzwerk abfragen muss, wäre es reine Zeitverschwendung, brav nacheinander zu warten. Führt man die Abfragen gleichzeitig aus, ist das Programm doppelt oder dreifach so schnell. In vielen Sprachen führt Nebenläufigkeit jedoch zu gefürchteten Fehlern („Race Conditions“). Zelyra verhindert diese Risiken durch einen strukturierten, sicheren Ansatz.

3. Verständliche Erklärung

Stell dir ein Restaurant vor:

In Zelyra nutzt du dafür den parallel-Block mit await:

fn berechne_teil_1() -> Int {
    return 40
}

fn berechne_teil_2() -> Int {
    return 60
}

fn main() {
    parallel {
        ergebnis_1 = await berechne_teil_1()
        ergebnis_2 = await berechne_teil_2()
    }
    print("Beide Teilaufgaben parallel abgeschlossen.")
}

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Parallele Teilberechnungen

fn berechne_statistiken() -> String {
    return "Statistiken berechnet"
}

fn lade_archiv() -> String {
    return "Archiv geladen"
}

fn main() {
    parallel {
        stats = await berechne_statistiken()
        archiv = await lade_archiv()
    }
    print("Paralleles Laden erfolgreich.")
}

Beispiel 2: Unabhängige Datenbeschaffung

fn summe_a() -> Int {
    return 100
}

fn summe_b() -> Int {
    return 250
}

fn main() {
    parallel {
        wert_a = await summe_a()
        wert_b = await summe_b()
    }
    print("Summen ermittelt.")
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. parallel { ... } führt unabhängige Operationen gleichzeitig aus.
  2. Jede Zeile im parallel-Block folgt dem Muster variable = await aufruf().
  3. Strukturierte Nebenläufigkeit verhindert Deadlocks und unkontrollierte Hintergrundprozesse.

7. Übungsaufgaben

8. Praxisaufgabe: Paralleles Laden von Aufgaben und Benutzerdaten

Beschleunige den Systemstart unserer Aufgabenverwaltung:

fn lade_benutzerprofil() -> String {
    return "Profil: Entwickler"
}

fn lade_aufgabenliste() -> String {
    return "5 Aufgaben geladen"
}

fn main() {
    print("Starte parallelen Abruf...")
    parallel {
        profil = await lade_benutzerprofil()
        aufgaben = await lade_aufgabenliste()
    }
    print("Dashboard bereit.")
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Wo darf das Schlüsselwort await in Zelyra verwendet werden?
  2. Welchem Format müssen die Anweisungen innerhalb eines parallel-Blocks folgen?
  3. Welcher Vorteil ergibt sich aus parallelen Abrufen gegenüber sequenzieller Abarbeitung?

TEIL VI – DATENBANKEN MIT ZELYRA

Kapitel 23: Warum Zelyra die Datenbank direkt versteht

1. Was lerne ich in diesem Kapitel?

In diesem Kapitel lernst du:

2. Warum ist das Thema wichtig?

In fast allen gängigen Web-Frameworks (PHP/Laravel, Python/Django, Node/TypeORM) existiert eine unsaubere Trennung: Entwickler schreiben SQL-Strings oder nutzen komplexe Abstraktionsschichten (ORMs). Das Ergebnis kennt jeder: Ein harmloser Dreizeiler feuert im Hintergrund 300 Queries ab (das gefürchtete N+1-Problem), oder Little Bobby Tables (Robert'); DROP TABLE Students;--) nutzt eine unmaskierte Lücke. Tippfehler in Spaltennamen wie user.emaiil werden oft erst bemerkt, wenn ein Nutzer im laufenden Betrieb einen Fehler 500 erhält. Zelyra beendet dieses Risiko: Wenn eine SQL-Abfrage nicht zum deklarierten Tabellenschema passt, verweigert der Compiler den Build sofort vor der Ausführung.

3. Verständliche Erklärung

In Zelyra definierst du deine Datenbank-Konfiguration direkt im Quelltext mit dem Schlüsselwort database:

database main {
    engine: mariadb
    database: "aufgaben_db"
}

fn main() {
    print("Datenbank-Konfiguration initialisiert.")
}

Wenn du Daten aus der Datenbank abfragst, schreibst du echtes SQL – aber der Compiler weiß genau, welche Spalten existieren:

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Datenbank und Tabelle deklarieren

database main {
    engine: mariadb
    database: "test_db"
}

table tasks {
    id: Id primary auto
    beschreibung: String(255) required
}

fn main() {
    print("Datenbank und Tabelle geprueft.")
}

Beispiel 2: SQL-Prüfung zur Compile-Zeit

database main {
    engine: mariadb
    database: "test_db"
}

table tasks {
    id: Id primary auto
    beschreibung: String(255) required
}

fn zeige_aufgaben() uses Database {
    daten = sql<Task[]> {
        SELECT id, beschreibung
        FROM tasks
    }
    print("SQL typgeprueft.")
}

fn main() uses Database {
    zeige_aufgaben()
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Zelyra schließt die Kluft zwischen Code und Datenbank.
  2. SQL-Abfragen werden zur Compile-Zeit typgeprüft.
  3. Datenbankzugriffe erfordern zwingend uses Database.

7. Übungsaufgaben

8. Praxisaufgabe: Die Datenbank der Aufgabenverwaltung anbinden

Erstelle das Fundament unserer Aufgabenverwaltung:

database main {
    engine: mariadb
    database: "zelyra_tasks"
}

table tasks {
    id: Id primary auto
    name: String(100) required
    erledigt: Bool
}

fn status_bericht() uses Database {
    liste = sql<Task[]> {
        SELECT id, name, erledigt
        FROM tasks
    }
    print("Datenbank fuer Aufgabenverwaltung einsatzbereit.")
}

fn main() uses Database {
    status_bericht()
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welches Problem lösen Zelyras typgeprüfte SQL-Blöcke gegenüber gewöhnlichen SQL-Strings?
  2. Welche Fähigkeit muss eine Funktion deklarieren, die sql ausführt?
  3. Wie leitet Zelyra den Typ Aufgabe aus der Tabelle aufgaben ab?

Kapitel 24: Tabellen definieren und Daten modellieren

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Das Datenmodell ist das Fundament jeder Anwendung. Wenn das Schema unsauber entworfen ist, schleppt man Datenmüll und Performanceprobleme über Jahre mit sich herum. Zelyra erzwingt von Anfang an klare Pflichtfelder, Typen und Integrität.

3. Verständliche Erklärung

Eine Tabelle (table) ist wie ein Aktenordner für gleichartige Datenblätter:

table kategorien {
    id: Id primary auto
    bezeichnung: String(50) required
}

Aus der Tabellendefinition table kategorien generiert Zelyra automatisch den Datentyp Kategorie mit den exakten Feldern.

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Einfache Tabelle mit Pflichtfeldern

database main {
    engine: mariadb
    database: "app_db"
}

table projekte {
    id: Id primary auto
    name: String(80) required
    aktiv: Bool
}

fn main() {
    print("Tabelle projekte deklariert.")
}

Beispiel 2: Tabelle mit Datums- und Zahlenfeldern

database main {
    engine: mariadb
    database: "app_db"
}

table zeiterfassungen {
    id: Id primary auto
    stunden: Float
    erfasst_am: Timestamp
}

fn main() {
    print("Tabelle zeiterfassungen deklariert.")
}

Beispiel 3: Verknüpfung zweier Tabellen über IDs

database main {
    engine: mariadb
    database: "app_db"
}

table tasks {
    id: Id primary auto
    beschreibung: String(200) required
    projekt_id: Id
}

fn main() {
    print("Beziehung aufgaben -> projekt_id angelegt.")
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Jede Tabelle benötigt einen Primärschlüssel id: Id primary auto.
  2. Das Attribut required verbietet leere Einträge auf Datenbank- und Sprachebene.
  3. Der Singularname der Tabelle (z. B. Aufgabe für aufgaben) wird zum automatischen Datentyp.

7. Übungsaufgaben

8. Praxisaufgabe: Vollständiges Schema für die Aufgabenverwaltung

Erstelle das produktive Datenmodell unserer Aufgabenverwaltung:

database main {
    engine: mariadb
    database: "zelyra_tasks"
}

table tasks {
    id: Id primary auto
    name: String(120) required
    beschreibung: String(500)
    prioritaet: Int
    ist_erledigt: Bool
}

fn main() {
    print("Vollstaendiges Aufgaben-Schema aktiv.")
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Wozu dient die Kennzeichnung auto beim Primärschlüssel?
  2. Was bewirkt das Schlüsselwort required an einer Tabellenspalte?
  3. Welcher Typname entsteht automatisch aus der Tabelle projekte?

Kapitel 25: Daten abfragen und verändern

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

SQL-Injection gehört seit über 20 Jahren zu den gefährlichsten Sicherheitslücken im Web: Ein Angreifer gibt in ein Suchfeld manipulierten Text ein und liest fremde Passwörter aus oder löscht Tabellen. Zelyra schützt deine Software konstruktiv: Parameter in SQL-Blöcken werden mit Doppelpunkt (:name) gebunden und von der Engine immer sicher escaped. Gleichzeitig sichern Transaktionen ab, dass bei Fehlern keine halben Buchungen stehenbleiben.

3. Verständliche Erklärung

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Einen neuen Datensatz einfügen

database main {
    engine: mariadb
    database: "tasks_db"
}

table tasks {
    id: Id primary auto
    name: String(100) required
    fertig: Bool
}

fn fuege_aufgabe_ein(text: String) uses Database {
    fertig_status = false
    transaction {
        sql {
            INSERT INTO tasks (name, fertig)
            VALUES (:text, :fertig_status)
        }
    }
    print("Aufgabe gespeichert.")
}

fn main() uses Database {
    fuege_aufgabe_ein("E-Mail beantworten")
}

Beispiel 2: Datensätze typisiert abfragen

database main {
    engine: mariadb
    database: "tasks_db"
}

table tasks {
    id: Id primary auto
    name: String(100) required
    fertig: Bool
}

fn lade_alle() uses Database {
    liste = sql<Task[]> {
        SELECT id, name, fertig
        FROM tasks
    }
    print("Aufgabenliste geladen.")
}

fn main() uses Database {
    lade_alle()
}

Beispiel 3: Datensatz aktualisieren

database main {
    engine: mariadb
    database: "tasks_db"
}

table tasks {
    id: Id primary auto
    name: String(100) required
    fertig: Bool
}

fn markiere_als_fertig(aufgabe_id: Int) uses Database {
    transaction {
        sql {
            UPDATE tasks
            SET fertig = true
            WHERE id = :aufgabe_id
        }
    }
    print("Status aktualisiert.")
}

fn main() uses Database {
    markiere_als_fertig(1)
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Binde Eingabewerte in SQL stets mit :parameter – das schützt vor SQL-Injection.
  2. Schreibende Operationen gehören in transaction { ... }.
  3. Mit zelyra db apply wird das definierte Schema auf die Datenbank übertragen.

7. Übungsaufgaben

8. Praxisaufgabe: Vollständige Datenbank-Operationen der Aufgabenverwaltung

Schreibe den Datenzugriff für unsere Aufgabenverwaltung:

database main {
    engine: mariadb
    database: "zelyra_tasks"
}

table tasks {
    id: Id primary auto
    name: String(100) required
    ist_erledigt: Bool
}

fn aufgabe_anlegen(aufgabe_name: String) uses Database {
    status_initial = false
    transaction {
        sql {
            INSERT INTO tasks (name, ist_erledigt)
            VALUES (:aufgabe_name, :status_initial)
        }
    }
    print("Aufgabe angelegt.")
}

fn aufgabe_abschliessen(ziel_id: Int) uses Database {
    transaction {
        sql {
            UPDATE tasks
            SET ist_erledigt = true
            WHERE id = :ziel_id
        }
    }
    print("Aufgabe abgeschlossen.")
}

fn main() uses Database {
    aufgabe_anlegen("Erstes Zelyra Projekt starten")
    aufgabe_abschliessen(1)
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Wie schützt Zelyra vor bösartigen SQL-Injection-Angriffen?
  2. Warum müssen schreibende SQL-Befehle in einem transaction-Block stehen?
  3. Welcher CLI-Befehl richtet die Datenbanktabellen anhand des Codes ein?

TEIL VII – WEBANWENDUNGEN UND FORMULARE

Kapitel 26: Webseiten ausgeben

1. Was lerne ich in diesem Kapitel?

In diesem Kapitel lernst du:

2. Warum ist das Thema wichtig?

Im klassischen Web-Development muss man oft drei verschiedene Welten verbinden: Einen Webserver (wie Nginx oder Apache), einen Router, eine Template-Engine (Blade, Jinja, Twig) und den Anwendungscode. Wenn man an einer Stelle vergisst, HTML-Sonderzeichen zu maskieren, können Angreifer bösartiges JavaScript einschleusen (XSS). In Zelyra ist der Webserver direkt integriert (zelyra serve), und das HTML-Escaping geschieht automatisch und unumgänglich.

3. Verständliche Erklärung

Mit dem Schlüsselwort page definierst du eine Webroute und das dazugehörige HTML:

page "/willkommen" {
    html {
        <h1>Willkommen bei Zelyra</h1>
        <p>Deine moderne Webanwendung laeuft!</p>
    }
}

Wenn du dynamische Werte anzeigen möchtest, setzt du sie einfach in geschweifte Klammern: {name}. Zelyra ersetzt den Platzhalter sicher durch den echten Text.

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Einfache statische Begrüßungsseite

page "/hallo" {
    html {
        <html>
            <body>
                <h1>Hallo Zelyra-Welt!</h1>
            </body>
        </html>
    }
}

Beispiel 2: Dynamische Route mit URL-Parameter

page "/benutzer/{name}" {
    html {
        <html>
            <body>
                <h1>Profil von {name}</h1>
                <p>Willkommen zurueck im Dashboard.</p>
            </body>
        </html>
    }
}

Beispiel 3: Sicheres Escaping gegen XSS-Angriffe Übergibt ein Nutzer als Namen <script>alert('hack')</script>, gibt Zelyra dies im Browser als harmlosen Text aus – das Skript wird niemals ausgeführt:

page "/sicher/{eingabe}" {
    html {
        <div>Eingabe: {eingabe}</div>
    }
}

Beispiel 4: Wiederverwendbare View-Layouts und Slots (ab Zelyra 0.1.41) Statt auf jeder Seite <html>, <head>, Header und Footer neu zu schreiben, definierst du mit view ein Layout. Ein View besitzt genau einen Hauptslot <slot /> sowie optionale benannte Slots mit sicherem Standardinhalt:

view AppShell {
    html {
        <html lang="de">
            <head><title>Zelyra Anwendung</title></head>
            <body>
                <header>
                    <slot name="header"><h1>Zelyra Portal</h1></slot>
                </header>
                <main>
                    <slot />
                </main>
                <footer>
                    <slot name="footer"><p>Erstellt mit Zelyra</p></slot>
                </footer>
            </body>
        </html>
    }
}

page "/dashboard" {
    view: AppShell
    html {
        <slot name="header"><h1>Mein Dashboard</h1></slot>
        <p>Der eigentliche Inhalt wird im Haupt-Slot der AppShell platziert.</p>
    }
}

Beispiel 5: Deklarative Suche, Filterung und Pagination (ab Zelyra 0.1.40) Für datengetriebene Seiten erzeugt Zelyra semantische Steuerungen für Suche, Sortierung und Seitenaufteilung automatisch, inklusive URL-Zustandserhalt:

database main {
    engine: mariadb
}

table tasks {
    id: Id primary auto
    title: String(100) required
    done: Bool default false
}

page "/tasks" {
    search { title }
    filter { done }
    sort { title }
    paginated 25

    load tasks = sql<Task[]> {
        SELECT id, title, done
        FROM tasks
        ORDER BY title
    }

    html {
        <h1>Aufgaben ({total} gesamt, Seite {page} von {pages})</h1>
        <ul>
            for task in tasks {
                <li>{task.title}</li>
            }
        </ul>
    }
}

Zelyra führt im Hintergrund automatisch die optimierte Zählabfrage (COUNT(*)) aus, bindet total und pages als sichere UInt-Variablen und rendert semantische Filter-Fieldsets.

Beispiel 6: Das integrierte Designsystem Zelyra UI (ab Version 1.0.6) Webanwendungen benötigen oft aufwendige Frontend-Build-Pipelines mit Node.js, Webpack, Vite und hunderten Megabytes an node_modules. Zelyra 1.0.6 bricht mit diesem Overhead: Das gesamte Designsystem zelyra-ui.v1.css wird lokal im Zelyra-Binary ausgeliefert.

page "/geschaefts-cockpit" {
    html {
        <div class="z-app-shell" data-z-ui data-z-theme="system" data-z-density="compact">
            <header class="z-header">
                <h2>Unternehmensportal</h2>
            </header>
            <main class="z-card">
                <div class="z-card__header">
                    <h3 class="z-card__title">Systemstatus</h3>
                </div>
                <div class="z-card__body">
                    <p>Alle Dienste laufen stabil und compilergeprueft.</p>
                    <a href="/invoices" class="z-button">Zu den Rechnungen</a>
                </div>
            </main>
        </div>
    }
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. page "/pfad" definiert eine Route und liefert geprüften HTML-Code aus.
  2. Variablen im HTML werden mit {variable} sicher interpoliert und automatisch escaped.
  3. view Name { ... } definiert wiederverwendbare Master-Layouts mit <slot /> und benannten Slots (<slot name="...">).
  4. search, filter und paginated erzeugen vollautomatische, semantische Query-Steuerungen mit Zustandsbewahrung in der URL.
  5. Mit zelyra serve startest du den integrierten HTTP-Server ohne externe Webserver-Konfiguration.

7. Übungsaufgaben

8. Praxisaufgabe: Startseite für die Aufgabenverwaltung

Erstelle die Web-Startseite unserer Aufgabenverwaltung:

page "/tasks" {
    html {
        <html>
            <head>
                <title>Zelyra Aufgabenverwaltung</title>
            </head>
            <body>
                <h1>Meine Aufgaben</h1>
                <p>Willkommen in deiner persoenlichen Aufgabenverwaltung.</p>
                <a href="/tasks/neu">Neue Aufgabe erstellen</a>
            </body>
        </html>
    }
}

Starte den Server mit zelyra serve main.zyl und öffne http://localhost:8080/tasks im Browser!

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welches Schlüsselwort leitet eine Webseiten-Definition ein?
  2. Wie bindet man dynamische Werte in den HTML-Quelltext ein?
  3. Warum ist XSS bei der HTML-Ausgabe in Zelyra standardmäßig ausgeschlossen?

Kapitel 27: Formulare und Benutzereingaben

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Eingaben von Nutzern sind die Hauptursache für Sicherheitslücken im Web: Angreifer übermitteln leere Pflichtfelder, manipulierte IDs oder nutzen fremde Browser-Sitzungen aus (CSRF-Attacken). In anderen Frameworks muss man Formulare mühsam von Hand mit Validierungsregeln, Fehleranzeigen und CSRF-Tokens zusammenbauen. Zelyras form-Konstrukt leitet die Eingabemaske direkt aus der Datenbanktabelle ab und sichert alles automatisch ab.

3. Verständliche Erklärung

Ein Formular verknüpft eine Eingabemaske mit einer Zieltabelle:

database main {
    engine: mariadb
}

table tasks {
    id: Id primary auto
    name: String(100) required
    beschreibung: String(500)
}

form TaskCreate -> tasks {
    fields {
        name
        beschreibung
    }
}

Zelyra generiert daraus:

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Basis-Formular für Kundendaten

database main {
    engine: mariadb
}

table customers {
    id: Id primary auto
    name: String(80) required
    email: Email?
}

form CustomerForm -> customers {
    fields {
        name
        email
    }
}

Beispiel 2: Formular mit benutzerdefinierten Aktionen

database main {
    engine: mariadb
}

table tasks {
    id: Id primary auto
    name: String(100) required
}

form NewTaskForm -> tasks {
    fields {
        name
    }
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. form Name -> zieltabelle generiert eine sichere Eingabemaske.
  2. Alle Validierungsregeln der Tabelle (Länge, Pflichtfeld, Typ) gelten automatisch.
  3. CSRF- und XSS-Schutz sind integral eingebaut.

7. Übungsaufgaben

8. Praxisaufgabe: Das Erstellungsformular für Aufgaben

Definiere das Eingabeformular für neue Aufgaben:

database main {
    engine: mariadb
}

table tasks {
    id: Id primary auto
    name: String(100) required
    prioritaet: Int
}

form TaskCreate -> tasks {
    fields {
        name
        prioritaet
    }
}

fn main() {
    print("Aufgaben-Formular bereit.")
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Wofür steht der Pfeil -> in form TaskCreate -> tasks?
  2. Warum müssen Entwickler in Zelyra keine manuellen CSRF-Tokens im HTML einfügen?
  3. Welche Spaltenprüfungen werden automatisch auf das Formular angewendet?

Kapitel 28: Das vollständige CRUD-Muster

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Über 80 % der Arbeit an Webanwendungen besteht aus dem immer gleichen Muster: Eine Tabelle anzeigen, Datensätze anlegen, bearbeiten und löschen. Entwickler verbringen Wochen damit, Controller, Routen, Formulare und Bestätigungsdialoge zu schreiben. In Zelyra erledigst du das in wenigen Zeilen deklarativem Code – absolut fehlerfrei, sicher und konsistent.

3. Verständliche Erklärung

Das Schlüsselwort crud fasst alle Operationen für eine Entität zusammen:

database main {
    engine: mariadb
}

table tasks {
    id: Id primary auto
    name: String(100) required
    erledigt: Bool default false
}

crud Task -> tasks {
    title: "Aufgabenverwaltung"
    view {
        fields {
            name
            erledigt
        }
        list {
            mode: cards
            empty: "Keine Aufgaben vorhanden."
        }
    }
}

Automatische Detail-Verlinkung bei ausgeblendeter ID : Wenn die technische id-Spalte im Block fields nicht aufgeführt ist (wie hier, wo nur name und erledigt sichtbar sind), verlinkt Zelyra automatisch das erste angezeigte Feld (name) mit der Detailseite des Datensatzes. Dies gilt sowohl für Tabellen- (table) als auch für Kachel-Layouts (cards).

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Ein vollständiges CRUD-Modul

database main {
    engine: mariadb
}

table tasks {
    id: Id primary auto
    name: String(100) required
    aktiv: Bool default true
}

crud Task -> tasks {
    title: "Aufgaben"

    view {
        fields {
            name
            aktiv
        }

        list {
            mode: cards
            empty: "Keine Aufgaben vorhanden."
        }

        detail {
            mode: cards
            title: "Aufgabendetails"
        }

        form {
            mode: cards
            title: "Aufgabe bearbeiten"
            submit: "Speichern"
        }

        delete {
            title: "Aufgabe loeschen"
            message: "Diese Aktion kann nicht rueckgaengig gemacht werden."
            submit: "Jetzt loeschen"
        }
    }
}

Beispiel 2: Benutzerdefinierte Aktionen im CRUD-Interface Du kannst individuelle Schaltflächen hinzufügen, z. B. um eine Aufgabe sofort als erledigt zu markieren:

database main {
    engine: mariadb
}

table tasks {
    id: Id primary auto
    name: String(100) required
    erledigt: Bool default false
}

crud Task -> tasks {
    title: "Aufgaben"
    view {
        fields {
            name
            erledigt
        }
    }

    action erledigen {
        label: "Als erledigt markieren"
        confirm: "Moechtest du diese Aufgabe abschliessen?"

        sql {
            UPDATE tasks
            SET erledigt = true
            WHERE id = :id
        }

        success "Aufgabe erfolgreich abgeschlossen."
        redirect "/tasks"
    }
}

Transaktionales Verhalten und Grenzen von CRUD-Aktionen:

  • Mehrere SQL-Anweisungen in einer Transaktion: Eine Action kann innerhalb des Blocks sql { ... } mehrere SQL-Anweisungen hintereinander ausführen (z. B. einen Datensatz aktualisieren und gleichzeitig eine Protokollzeile einfügen). Zelyra bündelt alle Anweisungen in einer einzigen MariaDB-Transaktion. Schlägt ein Statement fehl, wird die gesamte Transaktion atomar zurückgerollt.
  • Automatische Parameterbindung: Der Parameter :id wird automatisch aus dem URL-Pfad der gewählten Zeile gebunden. Mit field name: Type deklarierte Eingabefelder werden dem Benutzer im Dialog angezeigt, vorab validiert und als :name an die SQL-Statements übergeben.
  • Aktueller Ausführungsumfang: Seit 1.2.28 unterstützen CRUD-Actions typisierte Handler, Zeilen- und Sitzungsdaten sowie geprüfte Guards; Aktionen laufen im vorhandenen serverseitigen Transaktionskontext. Die konkreten erlaubten Ausdrücke und Effekte richten sich nach der dokumentierten Action-Syntax, nicht nach beliebigem Zelyra-Code.

Beispiel 3: CRUD-Ressource mit wiederverwendbarem View-Layout (ab Zelyra 0.1.43) Mit layout: ViewName bettest du alle generierten CRUD-Ansichten (Listen-, Detail-, Formular- und Löschdialoge) automatisch in ein zuvor deklariertes Seitenlayout ein:

view AppShell {
    html {
        <html lang="de">
            <body>
                <nav><a href="/">Start</a> | <a href="/tasks">Aufgaben</a></nav>
                <main>
                    <slot />
                </main>
            </body>
        </html>
    }
}

crud Task -> tasks {
    title: "Aufgabenverwaltung"
    layout: AppShell

    view {
        fields {
            name
            erledigt
        }
    }
}

Die generierte CRUD-Ressource übernimmt das Navigationsgerüst von AppShell, während alle Sicherheitsprüfungen, Rollen und CSRF-Tokens voll aktiv bleiben.

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. crud Name -> tabelle generiert eine vollständige, sichere Verwaltungsoberfläche.
  2. Ansichten (list, detail, form, delete) lassen sich flexibel anpassen.
  3. Benutzerdefinierte Aktionen (action) erweitern den Standard um individuelle Geschäftsregeln.

7. Übungsaufgaben

8. Praxisaufgabe: Das produktive CRUD-Interface unserer Aufgabenverwaltung

Kombiniere Datenbank, Tabelle und CRUD zu einem vollständigen System:

database main {
    engine: mariadb
    database: "tasks_app"
}

table tasks {
    id: Id primary auto
    name: String(120) required
    erledigt: Bool default false
}

crud Task -> tasks {
    title: "Meine Aufgabenverwaltung"

    view {
        fields {
            name
            erledigt
        }

        list {
            mode: cards
            empty: "Grossartig! Alle Aufgaben sind erledigt."
        }

        detail {
            mode: cards
            title: "Aufgabe ansehen"
        }

        form {
            mode: cards
            title: "Aufgabe erfassen oder bearbeiten"
            submit: "Aufgabe sichern"
        }

        delete {
            title: "Aufgabe loeschen"
            message: "Soll diese Aufgabe unwiderruflich entfernt werden?"
            submit: "Loeschen"
        }
    }
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welche vier Grundfunktionen umfasst die Abkürzung CRUD?
  2. Wie reagiert Zelyra, wenn in fields ein ungültiger Spaltenname steht?
  3. Welche Aufgabe erfüllt das Schlüsselwort action in einem CRUD-Block?

Kapitel 29: Benutzer, Passwörter und Sitzungen

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Sicherheit ist kein nachträgliches Add-on, das man am Tag vor dem Go-Live noch schnell drüberpinselt. Passwörter im Klartext oder mit antiken Algorithmen (wie MD5 oder SHA1) zu speichern, ist wie der Hausschlüssel unter der Fußmatte mit einem beleuchteten Pfeil darauf. In Zelyra ist Authentifizierung fest in der Spracharchitektur verankert: Passwörter werden standardmäßig mit speicherhartem Argon2 gehasht, Sitzungs-Tokens werden kryptografisch geschützt und Routenrechte werden deklarativ geprüft.

3. Verständliche Erklärung

Ein Authentifizierungsblock verbindet Benutzer, Sitzungen und Berechtigungen:

auth users {
    table: users
    sessions: auth_sessions
    permissions: user_permissions
}

table users {
    id: Id primary auto
    email: Email required unique
    password_hash: String(255) required
}

table auth_sessions {
    id: Id primary auto
    user: User required
    token_hash: String(64) required unique
    expires_at: Timestamp required
}

table user_permissions {
    id: Id primary auto
    user: User required
    permission: String(100) required
}

Um eine Webroute nur für angemeldete Nutzer freizugeben, schreibst du einfach:

auth users {
    table: users
    sessions: auth_sessions
    permissions: user_permissions
}

table users {
    id: Id primary auto
    email: Email required unique
    password_hash: String(255) required
}

table auth_sessions {
    id: Id primary auto
    user: User required
    token_hash: String(64) required unique
    expires_at: Timestamp required
}

table user_permissions {
    id: Id primary auto
    user: User required
    permission: String(100) required
}

page "/geheim" {
    requires auth
    html {
        <h1>Nur fuer angemeldete Nutzer sichtbar!</h1>
    }
}

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Die Standardtabellen für Authentifizierung

auth users {
    table: users
    sessions: auth_sessions
    permissions: user_permissions
}

table users {
    id: Id primary auto
    email: Email required unique
    password_hash: String(255) required
    active: Bool default true
}

table auth_sessions {
    id: Id primary auto
    user: User required
    token_hash: String(64) required unique
    expires_at: Timestamp required
}

table user_permissions {
    id: Id primary auto
    user: User required
    permission: String(100) required
}

Beispiel 2: Geschützte Seite mit Rechteprüfung

auth users {
    table: users
    sessions: auth_sessions
    permissions: user_permissions
}

table users {
    id: Id primary auto
    email: Email required unique
    password_hash: String(255) required
    active: Bool default true
}

table auth_sessions {
    id: Id primary auto
    user: User required
    token_hash: String(64) required unique
    expires_at: Timestamp required
}

table user_permissions {
    id: Id primary auto
    user: User required
    permission: String(100) required
}

page "/dashboard" {
    requires auth
    permits "tasks.view"

    html {
        <h1>Aufgaben-Dashboard</h1>
        <p>Du bist autorisiert.</p>
    }
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. auth deklariert Benutzer, Sitzungen und Berechtigungen an einer zentralen Stelle.
  2. Geschützte Seiten erfordern requires auth und optional permits "recht".
  3. Passwörter werden ausschließlich als sichere Argon2-Hashes gespeichert.

7. Übungsaufgaben

8. Praxisaufgabe: Geschützte Aufgabenverwaltung

Schütze die Aufgabenverwaltung vor unbefugtem Zugriff:

auth users {
    table: users
    sessions: auth_sessions
    permissions: user_permissions
}

table users {
    id: Id primary auto
    email: Email required unique
    password_hash: String(255) required
    active: Bool default true
}

table auth_sessions {
    id: Id primary auto
    user: User required
    token_hash: String(64) required unique
    expires_at: Timestamp required
}

table user_permissions {
    id: Id primary auto
    user: User required
    permission: String(100) required
}

page "/meine-aufgaben" {
    requires auth

    html {
        <h1>Geschuetzter Aufgabenbereich</h1>
        <p>Nur fuer authentifizierte Benutzer zugaenglich.</p>
    }
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welcher moderne Hash-Algorithmus wird von Zelyra für Passwörter verwendet?
  2. Mit welchem Befehl wird eine Webroute für unbefugte Besucher gesperrt?
  3. Wozu dient die Tabelle auth_sessions?

Kapitel 30: APIs und Datenaustausch

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Moderne Software lebt nicht isoliert: Mobile Apps (iOS/Android), Frontend-Frameworks (Vue, React) oder Partnersysteme müssen mit deinem Backend kommunizieren. Bei herkömmlichen APIs veraltet die Dokumentation oft schon am Tag nach dem Release. In Zelyra ist die API-Definition der Code selbst: Jede Route, jedes Eingabefeld und jeder Fehlercode ist exakt typisiert – und die OpenAPI-Spezifikation wird daraus vollautomatisch abgeleitet.

3. Verständliche Erklärung

Mit dem Schlüsselwort api deklarierst du einen Web-Endpunkt:

type TaskId = Id

table tasks {
    id: TaskId primary auto
    name: String required
}

api GET "/api/tasks/{id}" {
    input {
        id: TaskId
    }
    output Task
    errors {
        404 NotFound
    }
}

fn main() {
    print("API-Endpunkt definiert.")
}

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Ein GET-Endpunkt mit Rückgabetyp

type TaskId = Id

table tasks {
    id: TaskId primary auto
    name: String required
}

api GET "/tasks/{id}" {
    input {
        id: TaskId
    }
    output Task
    errors {
        404 NotFound
    }
}

fn main() {
    print("GET API geprueft.")
}

Beispiel 2: Ein POST-Endpunkt zum Anlegen von Daten

type TaskId = Id

table tasks {
    id: TaskId primary auto
    name: String(100) required
}

api POST "/tasks" {
    input {
        name: String
    }
    output Task
    errors {
        400 ValidationError
    }
}

fn main() {
    print("POST API geprueft.")
}

Beispiel 3: OpenAPI-Dokumentation erzeugen Mit dem Befehl:

zelyra doc main.zyl --openapi

generiert Zelyra eine normgerechte openapi.json, die du direkt in Swagger-UI oder Postman importieren kannst.

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. api METHOD "/pfad" deklariert eine typsichere REST-Schnittstelle.
  2. input, output und errors beschreiben den Datenvertrag der Schnittstelle lückenlos.
  3. zelyra doc --openapi erzeugt OpenAPI-Spezifikationen direkt aus dem Quelltext.

7. Übungsaufgaben

8. Praxisaufgabe: Die REST-API für unsere Aufgabenverwaltung

Definiere die öffentliche Programmierschnittstelle unserer Aufgabenverwaltung:

type TaskId = Id

table tasks {
    id: TaskId primary auto
    name: String(120) required
    erledigt: Bool
}

api GET "/api/tasks/{id}" {
    input {
        id: TaskId
    }
    output Task
    errors {
        404 NotFound
    }
}

api POST "/api/tasks" {
    input {
        name: String
    }
    output Task
    errors {
        400 ValidationError
    }
}

fn main() {
    print("Aufgaben REST-API einsatzbereit.")
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welche vier Abschnitte umfasst eine vollständige api-Deklaration?
  2. Warum ist die automatische OpenAPI-Generierung gegenüber manuellen Dokumentationen überlegen?
  3. Was geschieht, wenn ein Client ungültige Daten an einen input-Block sendet?

TEIL VIII – DIE BESONDERHEITEN VON ZELYRA

Kapitel 31: Lesbarkeit als oberstes Gebot

1. Was lerne ich in diesem Kapitel?

In diesem Kapitel lernst du:

2. Warum ist das Thema wichtig?

Viele Programmiersprachen erlauben es, denselben Sachverhalt auf zehn verschiedene Arten auszudrücken – oft in ultrakompakten Einzeilern mit Sonderzeichen, die nach drei Monaten niemand mehr versteht. Schreibe deinen Code immer so, als wäre die Person, die ihn in sechs Monaten warten muss, ein ungeduldiger Kollege, der die Kaffeemaschine kontrolliert und weiß, wo du sitzt. In großen Teams und langfristigen Projekten führt kryptischer Code zu enormen Wartungskosten. Zelyra folgt dem Grundsatz: Es gibt genau einen offensichtlichen, lesbaren Weg, eine Aufgabe zu lösen.

3. Verständliche Erklärung

Lesbarkeit in Zelyra bedeutet:

fn berechne_gesamtzeit(aufgaben_dauern: Int[]) -> Int {
    mutable summe = 0
    for dauer in aufgaben_dauern {
        summe = summe + dauer
    }
    return summe
}

fn main() {
    zeiten: Int[] = [15, 30, 45]
    print(berechne_gesamtzeit(zeiten))
}

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Selbsterklärende Funktionssignaturen

fn ist_aufgabe_ueberfaellig(frist_tage: Int) -> Bool {
    return frist_tage < 0
}

fn main() {
    print(ist_aufgabe_ueberfaellig(-2))
}

Beispiel 2: Verständliche Kontrollstrukturen

fn status_anzeige(status_code: Int) -> String {
    match status_code {
        1 => {
            return "Neu"
        }
        2 => {
            return "In Bearbeitung"
        }
        3 => {
            return "Erledigt"
        }
        _ => {
            return "Unbekannt"
        }
    }
}

fn main() {
    print(status_anzeige(2))
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Schreibe Code für den Menschen, der ihn in sechs Monaten warten muss.
  2. zelyra fmt garantiert einen einheitlichen, lesbaren Programmierstil im gesamten Projekt.
  3. Klare, sprechende Bezeichner sind die beste Dokumentation.

7. Übungsaufgaben

8. Praxisaufgabe: Lesbare Status- und Filterlogik

Gestalte die Filterlogik unserer Aufgabenverwaltung maximal verständlich:

fn ist_dringend_und_offen(prioritaet: Int, erledigt: Bool) -> Bool {
    ist_prioritaet_eins = prioritaet == 1
    ist_noch_nicht_erledigt = !erledigt
    return ist_prioritaet_eins && ist_noch_nicht_erledigt
}

fn main() {
    print(ist_dringend_und_offen(1, false))
    print(ist_dringend_und_offen(2, false))
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Warum spart gut lesbarer Code auf lange Sicht Zeit und Geld?
  2. Welcher Zelyra-CLI-Befehl formatiert Quelldateien automatisch?
  3. Warum verzichtet Zelyra auf übermäßig viele alternative Schreibweisen für dieselbe Logik?

Kapitel 32: KI-Nativität – Warum Zelyra perfekt für KI-Assistenten ist

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Die meisten Programmiersprachen wurden vor Jahrzehnten entwickelt – ausschließlich für menschliche Tastatureingaben. Wenn moderne KI-Assistenten Code in Python oder JavaScript schreiben, wirken sie manchmal wie geniale Praktikanten nach fünf Dosen Energydrink: Sie tippen rasend schnell, erfinden aber gelegentlich Methoden, verwechseln Typen oder übersehen Seiteneffekte. Zelyra wurde von Grund auf so entworfen, dass menschliche Entwickler und KI-Assistenten optimal zusammenarbeiten können: Der Compiler liefert strukturierte JSON-Diagnosen und mit Typed Holes _ exakte Lückentexte.

3. Verständliche Erklärung

Zelyra unterstützt KI-Entwicklung durch vier Schlüsselmerkmale:

  1. Eindeutige, kontextfreie Grammatik: Die Sprache hat keine Mehrdeutigkeiten.
  2. Maschinenlesbare JSON-Ausgabe: Fast alle Befehle bieten --format json (z. B. zelyra check --format json), sodass KIs Fehlermeldungen direkt als strukturierte Daten erfassen.
  3. Typed Holes (_): Wenn du oder die KI nicht genau wissen, wie ein Wert berechnet wird, setzt man einen Unterstrich _ ein. Der Compiler meldet sofort exakt: Welcher Typ wird erwartet? Welche Variablen sind verfügbar? Welche Verträge gelten?
  4. Auswirkungsanalyse (zelyra impact): Zelyra berechnet vorab genau, welche Programmteile von einer Änderung betroffen sind.

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Typisierte Verträge leiten die KI fehlerfrei Durch Verträge weiß die KI ohne Raten, welche Randbedingungen gelten:

fn normalisiere_skala(wert: Int) -> Int
    requires { wert >= 0 && wert <= 100 }
    ensures { result >= 0 && result <= 10 }
{
    return wert / 10
}

fn main() {
    print(normalisiere_skala(85))
}

Beispiel 2: Maschinenlesbare Fehleranalyse Führt ein KI-Tool den Befehl:

zelyra check main.zyl --format json

aus, erhält es präzise JSON-Objekte mit exaktem Fehlercode, Zeile, Spalte und Lösungshinweis.

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Zelyra ist die erste KI-native Sprache: Eindeutig, strukturiert und werkzeugfreundlich.
  2. Typed Holes _ dienen als präzise Arbeitsaufträge an den Compiler und KI-Assistenten.
  3. --format json ermöglicht nahtlose Integration in moderne KI-Agenten und IDEs.

7. Übungsaufgaben

8. Praxisaufgabe: KI-unterstützte Erweiterung der Aufgabenverwaltung

Schreibe eine wohlstrukturierte Funktionssignatur mit Vertrag, die sich perfekt von einer KI vervollständigen lässt:

fn berechne_restzeit(ziel_stunde: Int, aktuelle_stunde: Int) -> Int
    requires { ziel_stunde >= aktuelle_stunde }
    ensures { result >= 0 }
{
    return ziel_stunde - aktuelle_stunde
}

fn main() {
    rest = berechne_restzeit(18, 14)
    print(rest)
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Wofür steht das Konzept der „Typed Holes“ in Zelyra?
  2. Warum profitieren KI-Systeme von der --format json-Option des Compilers?
  3. Wie helfen Verträge (requires, ensures) einer KI beim Erzeugen von korrektem Code?

Kapitel 33: Sicherheit durch Fähigkeiten (Capabilities)

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

In heutigen Ökosystemen bindet man oft hunderte Bibliotheken von Drittanbietern ein. Wenn ein winziges Paket manipuliert wird, kann es unbemerkt Passwörter auslesen, Festplatten verschlüsseln oder Daten ins Internet funken (Supply-Chain-Angriffe). Capabilities sind wie ein elektronischer Dienstausweis: Wer nur einen Chip für den Aufenthaltsraum besitzt, kann nicht nachts heimlich den Serverraum betreten. In Zelyra kann eine Funktion ohne ausdrückliche Deklaration von uses Network oder uses FileSystem technisch kein einziges Byte nach außen senden – der Compiler verweigert den Dienst!

3. Verständliche Erklärung

Stell dir Zelyras Capability-System wie ein Sicherheitsschloss vor:

fn sichere_operation() {
    # Diese Funktion hat KEINE Capabilities.
    # Sie kann unmoeglich Schaden auf der Festplatte oder im Netzwerk anrichten!
    print("Garantiert seiteneffektfrei.")
}

fn main() {
    sichere_operation()
}

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Saubere Deklaration von Umgebungsvariablen

fn lese_konfiguration(schluessel: String) -> Option<String>
    uses Environment
{
    return env(schluessel)
}

fn main() uses Environment {
    print("Konfigurationszugriff erlaubt.")
}

Beispiel 2: Datenbankzugriff mit Capability

database main {
    engine: mariadb
    database: "tasks_db"
}

table tasks {
    id: Id primary auto
    name: String required
}

fn lade_daten() uses Database {
    daten = sql<Task[]> {
        SELECT id, name
        FROM tasks
    }
    print("Datenbankzugriff gewaehrt.")
}

fn main() uses Database {
    lade_daten()
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Keine Funktion kann heimlich auf Dateien, Datenbanken oder das Netzwerk zugreifen.
  2. Alle Seiteneffekte sind transparent in der Funktionssignatur dokumentiert.
  3. Reine Funktionen ohne Capabilities sind garantiert manipulationssicher.

7. Übungsaufgaben

8. Praxisaufgabe: Berechtigungs-Architektur der Aufgabenverwaltung

Isoliere die Berechtigungen in unserer Aufgabenverwaltung:

# 1. Reine Logik: KEINE Berechtigungen noetig
fn ist_bereit_fuer_export(anzahl_aufgaben: Int) -> Bool {
    return anzahl_aufgaben > 0
}

# 2. I/O-Logik: Explizite Dateisystem-Berechtigung
fn fuehre_export_durch(datei: String, inhalt: String) uses FileSystem {
    write_text(datei, inhalt)
    print("Export vollzogen.")
}

fn main() uses FileSystem {
    if ist_bereit_fuer_export(5) {
        fuehre_export_durch("aufgaben.txt", "Aufgabe 1")
    }
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Nenne drei System-Capabilities von Zelyra.
  2. Warum müssen auch übergeordnete Aufrufer-Funktionen Capabilities deklarieren?
  3. Wie schützt Zelyra vor schadhaftem Fremdcode aus Paketmanagern?

Kapitel 34: Zelyra im Vergleich

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Keine Programmiersprache ist für jeden Zweck perfekt: C und Rust sind unschlagbar für Betriebssystemkerne, Python dominiert die Datenwissenschaft, JavaScript das Frontend. Wer aber moderne, datenbankgestützte Geschäftsanwendungen und Web-Backends bauen will, kämpft in diesen Sprachen oft mit historischem Ballast. Zelyra vereint das Beste aus diesen Welten.

3. Verständliche Erklärung: Der Sprachvergleich

Merkmal Python PHP / Laravel TypeScript / Node Rust Zelyra
Typisierung Dynamisch Dynamisch/Optional Statisch (wird zu JS) Statisch (sehr streng) Statisch & Eindeutig
Null-Sicherheit None-Crashes möglich null-Crashes möglich undefined-Crashes Absolut (Option) Absolut (Option)
SQL-Integration ORM (Strings) ORM (Eloquent) ORM (Prisma/TypeORM) Diesel/SQLx Nativ & Typgeprüft
Verträge (Contracts) Nein (nur assert) Nein Nein Dritt-Bibliotheken Eingebaut (requires)
Sicherheits-Capabilities Nein (Vollzugriff) Nein (Vollzugriff) Nein (Vollzugriff) Nein Eingebaut (uses ...)
KI-Werkzeugunterstützung Mittel (Mehrdeutig) Mittel Mittel Schwer für KIs Nativ (JSON, Typed Holes)

4. Kleine, aufeinander aufbauende Beispiele

Vergleich: Wie Zelyra Fehler verhindert, die in anderen Sprachen passieren

In Python/JS (potenzieller Laufzeitabsturz bei null): Ein unbemerkter fehlender Wert führt zum Servercrash: AttributeError: 'NoneType' object has no attribute 'title'.

In Zelyra (garantiert abgefangen zur Compilezeit):

fn zeige_titel(opt_titel: Option<String>) {
    match opt_titel {
        Some(t) => {
            print("Titel: " + t)
        }
        None => {
            print("Kein Titel vorhanden.")
        }
    }
}

fn main() {
    zeige_titel(Some("Projekt X"))
    zeige_titel(None)
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Zelyra verbindet einen zugänglichen Entwicklungsablauf mit einem eigenen statischen Typsystem und Compilerprüfungen. Welche Probleme erkannt werden, hängt vom aktuellen Prüfumfang ab.
  2. Datenbanken, Webformulare und Schnittstellen sind native Sprachbausteine statt externer Bibliotheken.
  3. Sicherheit und Korrektheit werden nicht nachträglich hineingetestet, sondern von Anfang an erzwungen.

7. Übungsaufgaben

8. Praxisaufgabe: Die Aufgabenverwaltung als Zelyra-Vorzeigeprojekt

Führe alle Kernstärken in einem prägnanten Ausschnitt zusammen:

database main {
    engine: mariadb
    database: "tasks_demo"
}

table tasks {
    id: Id primary auto
    name: String(100) required
    erledigt: Bool default false
}

fn zaehle_offene() -> Int uses Database {
    offene = sql<Task[]> {
        SELECT id, name, erledigt
        FROM tasks
        WHERE erledigt = false
    }
    return len(offene)
}

fn main() uses Database {
    anzahl = zaehle_offene()
    print("Offene Aufgaben ermittelt.")
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welchen Vorteil bietet Zelyras Option-Typ gegenüber Pythons None oder JavaScripts null?
  2. Warum ist die native Datenbankintegration in Zelyra sicherer als traditionelle ORM-Bibliotheken?
  3. Welche Rolle spielen Capabilities beim Schutz vor bösartigen Fremdpaketen?

TEIL IX – VOM ENTWURF ZUR FERTIGEN ANWENDUNG

Kapitel 35: Software planen – Von der Idee zum Entwurf

1. Was lerne ich in diesem Kapitel?

In diesem Kapitel lernst du:

2. Warum ist das Thema wichtig?

Der größte Fehler von Anfängern (und unvorsichtigen Profis) ist es, sofort loszutippen, ohne den Datenfluss zu planen. Wer während des Programmierens merkt, dass ein zentrales Tabellenfeld oder eine Beziehung fehlt, muss oft Tage damit verbringen, bestehenden Code mühsam umzuschreiben. Zelyra belohnt gründliche Planung: Sobald dein table-Schema steht, leiten sich Formulare, Validierungen und APIs fast wie von selbst ab.

3. Verständliche Erklärung

Jedes gute Softwareprojekt durchläuft vier Planungsphasen:

  1. Zweck und Zielgruppe klären: Wer nutzt das System? Welche Kernaufgabe muss gelöst werden? (z. B. „Ein Teamleiter möchte Aufgaben anlegen, zuweisen und als erledigt markieren“).
  2. Datenmodell entwerfen: Welche Objekte gibt es? Welche Felder sind Pflicht? (z. B. tasks mit name, prioritaet, ist_erledigt).
  3. Sicherheits- und Zugriffsregeln: Wer darf was tun? Benötigen wir Authentifizierung?
  4. Schrittweise Implementierung: Erst das Schema (table), dann die Logik (fn), dann die Webansichten (crud/page).

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Der erste Meilenstein – Das Datenmodell

database main {
    engine: mariadb
    database: "aufgaben_planer"
}

table tasks {
    id: Id primary auto
    name: String(100) required
    prioritaet: Int default 2
    erledigt: Bool default false
}

fn main() {
    print("Planungsschritt 1: Schema steht.")
}

Beispiel 2: Planung der Geschäftslogik als reine Funktionen

fn validiere_frist(tage: Int) -> Bool {
    return tage >= 0
}

fn main() {
    print(validiere_frist(3))
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Wer die Planung vernachlässigt, plant das Scheitern.
  2. Ein klares Datenmodell ist das Rückgrat jeder erfolgreichen Anwendung.
  3. Zerlege große Probleme in kleine, unabhängig überprüfbare Funktionen.

7. Übungsaufgaben

8. Praxisaufgabe: Der vollständige Architekturplan unserer Aufgabenverwaltung

Führe alle Planungselemente der Aufgabenverwaltung zusammen:

database main {
    engine: mariadb
    database: "tasks_pro"
}

table tasks {
    id: Id primary auto
    name: String(120) required
    prioritaet: Int default 1
    erledigt: Bool default false
}

fn berechne_dringlichkeit(prioritaet: Int, verbleibende_tage: Int) -> String {
    if prioritaet == 1 {
        return "HOECHSTE PRIORITAET"
    }
    if verbleibende_tage <= 1 {
        return "DRINGEND WEGEN FRIST"
    }
    return "NORMAL"
}

fn main() {
    status = berechne_dringlichkeit(1, 5)
    print("Architektur-Plan verifiziert: " + status)
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welche vier Phasen durchläuft ein professioneller Software-Entwurf?
  2. Warum sollte das Datenmodell vor der Benutzeroberfläche entworfen werden?
  3. Wie helfen Vorbedingungen bei der präzisen Anforderungsdefinition?

Kapitel 36: Architektur und saubere Codestruktur

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Wenn Datenzugriff, Geschäftsregeln und HTML-Ausgabe wild durcheinandergewürfelt werden, entsteht unwartbarer Code. Wenn sich später das Datenbanklayout ändert, zerbricht plötzlich die Weboberfläche. Eine saubere Architektur zieht klare Trennlinien: Jede Schicht hat eine einzige Verantwortlichkeit.

3. Verständliche Erklärung

Eine saubere Zelyra-Anwendung gliedert sich in drei klare Schichten:

  1. Daten- und Persistenzschicht: Tabellendefinitionen (table) und typisierte SQL-Abfragen.
  2. Geschäftslogikschicht: Reine Rechen- und Validierungsfunktionen mit Verträgen (requires, ensures).
  3. Präsentations- und Schnittstellenschicht: Weboberflächen (crud, page) und REST-Endpunkte (api).
# 1. Datenmodell
table tasks {
    id: Id primary auto
    name: String required
}

# 2. Geschäftslogik
fn formatiere_name(rohtext: String) -> String {
    return "[AUFGABE] " + rohtext
}

# 3. Einstieg / Ablauf
fn main() {
    print(formatiere_name("Server pruefen"))
}

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Trennung von Logik und I/O

# Reine Rechenfunktion: Keine Capabilities noetig
fn berechne_prozent(wert: Int, max_wert: Int) -> Int
    requires { max_wert > 0 && wert >= 0 }
{
    return (wert * 100) / max_wert
}

# I/O-Funktion: Nutzt die Logik und gibt sie aus
fn main() {
    prozent = berechne_prozent(45, 50)
    print(prozent)
}

Beispiel 2: Strukturierung durch aussagekräftige Namen

table settings {
    id: Id primary auto
    app_name: String(60) required
}

fn zeige_systeminfo(name: String) {
    print("System laeuft: " + name)
}

fn main() {
    zeige_systeminfo("Zelyra Task Suite")
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Trenne Datenmodell, Geschäftsregeln und Darstellung strikt voneinander.
  2. Geschäftslogik sollte möglichst frei von Seiteneffekten und Capabilities sein.
  3. Saubere Schichten machen Anwendungen zukunftssicher und einfach erweiterbar.

7. Übungsaufgaben

8. Praxisaufgabe: Schichtenarchitektur für die Aufgabenverwaltung

Implementiere das Schichtenmodell für unsere Aufgabenverwaltung:

database main {
    engine: mariadb
    database: "tasks_architecture"
}

# Schicht 1: Persistenz
table tasks {
    id: Id primary auto
    name: String required
    erledigt: Bool default false
}

# Schicht 2: Geschaeftslogik
fn ist_aufgabe_wichtig(name: String, dringend: Bool) -> Bool {
    return dringend
}

# Schicht 3: Anwendung / Ausfuehrung
fn main() uses Database {
    wichtig = ist_aufgabe_wichtig("Steuern einreichen", true)
    print("Aufgaben-Architektur geprueft.")
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welche drei Schichten bilden das Fundament einer sauberen Zelyra-Anwendung?
  2. Warum sollte Kern-Geschäftslogik möglichst ohne Capabilities auskommen?
  3. Welche Vorteile bietet die Trennung von Präsentation und Datenzugriff bei Re-Designs?

Kapitel 37: Konfiguration und Umgebungsvariablen

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Einer der schnellsten Wege, um unfreiwillig auf der Startseite von Sicherheitsblogs zu landen, ist das versehentliche Einchecken von Datenbank-Passwörtern oder API-Schlüsseln in öffentliche Git-Repositories. Zudem muss sich eine Anwendung in Entwicklung, Test und Produktion unterschiedlich verhalten (z. B. andere Datenbank-Hosts). Umgebungsvariablen (uses Environment) trennen Code und Geheimnisse sauber voneinander – damit dein Code quelloffen sein kann, deine Passwörter aber geheim bleiben.

3. Verständliche Erklärung

In Zelyra greifst du über die Funktion env() auf Umgebungsvariablen zu. Weil eine Variable in der Umgebung existieren kann oder fehlen kann, liefert env() immer ein Option<String> zurück:

fn lese_port() -> String uses Environment {
    opt_port = env("APP_PORT")
    match opt_port {
        Some(p) => {
            return p
        }
        None => {
            return "8080"
        }
    }
}

fn main() uses Environment {
    port = lese_port()
    print("Server lauscht auf Port: " + port)
}

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Datenbank-Host konfigurieren

fn hole_db_host() -> String uses Environment {
    match env("DB_HOST") {
        Some(host) => {
            return host
        }
        None => {
            return "127.0.0.1"
        }
    }
}

fn main() uses Environment {
    print("Verbinde mit: " + hole_db_host())
}

Beispiel 2: Debug-Modus dynamisch abfragen

fn ist_debug_aktiv() -> Bool uses Environment {
    match env("APP_DEBUG") {
        Some(wert) => {
            return wert == "true"
        }
        None => {
            return false
        }
    }
}

fn main() uses Environment {
    if ist_debug_aktiv() {
        print("Debug-Modus ist AN")
    } else {
        print("Debug-Modus ist AUS")
    }
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. Sensible Zugangsdaten gehören niemals in den Versionskontroll-Quelltext.
  2. env(name) liefert ein Option<String> und erfordert uses Environment.
  3. Stelle für fehlende Umgebungsvariablen immer sichere Standardwerte bereit.

7. Übungsaufgaben

8. Praxisaufgabe: Konfigurationszentrale für die Aufgabenverwaltung

Schreibe den Konfigurations-Loader für unsere Aufgabenverwaltung:

fn lade_app_titel() -> String uses Environment {
    match env("APP_TITLE") {
        Some(titel) => {
            return titel
        }
        None => {
            return "Zelyra Aufgabenverwaltung 0.1"
        }
    }
}

fn main() uses Environment {
    print("System gestartet: " + lade_app_titel())
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Warum dürfen geheime API-Schlüssel niemals im Quelltext fest hinterlegt sein?
  2. Welchen Datentyp liefert die Funktion env() zurück?
  3. Welche Capability wird für den Zugriff auf Umgebungsvariablen benötigt?

Kapitel 38: Fehlersuche und Optimierung

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Selbst bei sorgfältigster Programmierung läuft nicht immer alles auf Anhieb glatt. Vielleicht ist der Datenbankport blockiert, eine Konfiguration unvollständig oder eine Schleife berechnet unnötige Schritte. Wer planlos herumprobiert, verliert Stunden. Systematisches Debugging mit den passenden Zelyra-Werkzeugen führt dagegen in wenigen Minuten zur Lösung.

3. Verständliche Erklärung

Zelyra gibt dir ein Schweizer Taschenmesser für die Fehlerdiagnose an die Hand:

zelyra doctor main.zyl

Wenn die MariaDB-Verbindung nicht erreichbar ist, meldet doctor sofort die Ursache, anstatt dich im Unklaren zu lassen.

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Systematische Kontrollausgaben

fn berechne_summe(zahlen: Int[]) -> Int {
    mutable summe = 0
    for z in zahlen {
        summe = summe + z
    }
    return summe
}

fn main() {
    werte: Int[] = [10, 20, 30]
    ergebnis = berechne_summe(werte)
    print("Berechnetes Ergebnis:")
    print(ergebnis)
}

Beispiel 2: Absicherung vor Endlosschleifen durch Invarianten

fn sichere_zaehlung(grenze: Int) -> Int
    requires { grenze > 0 }
{
    mutable i = 0
    while i < grenze
        invariant { i >= 0 }
    {
        i = i + 1
    }
    return i
}

fn main() {
    print(sichere_zaehlung(10))
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. zelyra doctor ist der erste Schritt bei Verbindungsproblemen und Umgebungsfehlern.
  2. Invarianten und Verträge verhindern logische Fehlberechnungen.
  3. Systematische Fehlersuche ist schneller und sicherer als blindes Ausprobieren.

7. Übungsaufgaben

8. Praxisaufgabe: Selbstdiagnose-Routine der Aufgabenverwaltung

Baue einen internen Gesundheits-Check für die Aufgabenverwaltung:

fn fuehre_selbsttest_durch() -> Bool {
    test_ok = 1 + 1 == 2
    return test_ok
}

fn main() {
    print("Starte System-Selbsttest...")
    if fuehre_selbsttest_durch() {
        print("[OK] System arbeitet einwandfrei.")
    } else {
        print("[FEHLER] Interner Systemfehler.")
    }
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welche Aspekte überprüft der CLI-Befehl zelyra doctor?
  2. Wie grenzt man einen Fehler in einer längeren Berechnung am besten ein?
  3. Welche Rolle spielen Schleifeninvarianten bei der Fehlersuche?

Kapitel 39: Bereitstellung und Betrieb

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Eine Software nützt niemandem, wenn sie nur auf dem Entwickler-Laptop läuft. Sie muss auf einem Server oder in der Cloud rund um die Uhr stabil erreichbar sein. In anderen Umgebungen erfordert das Deployment oft komplizierte Anleitungen mit PHP-FPM, Webserver-Vhosts und Prozessmanagern. Zelyra vereinfacht den Betrieb radikal: Eine einzelne Konfiguration und ein schlanker Container genügen.

3. Verständliche Erklärung

Zelyra bringt seinen eigenen Hochleistungs-Webserver direkt mit:

zelyra serve src/main.zyl 0.0.0.0:8080

Für den professionellen Betrieb verpackst du dein Projekt in einen Docker-Container:

4. Kleine, aufeinander aufbauende Beispiele

Beispiel 1: Produktionsreife Projektstruktur

# zelyra.toml
[package]
name = "aufgaben_produktion"
version = "1.0.0"

[capabilities]
database = true
filesystem = false
network = true

Beispiel 2: Saubere Hauptdatei für den Webbetrieb

database main {
    engine: mariadb
    database: "tasks_prod"
}

table tasks {
    id: Id primary auto
    name: String(120) required
    fertig: Bool default false
}

page "/" {
    html {
        <h1>Zelyra Aufgabenverwaltung live</h1>
        <p>Produktivsystem aktiv und sicher.</p>
    }
}

Beispiel 3: Startbefehl für den Server Auf dem Produktionsserver genügt:

zelyra db apply src/main.zyl
zelyra serve src/main.zyl 0.0.0.0:80

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. zelyra serve startet den integrierten HTTP-Server ohne externe Webserver-Abhängigkeiten.
  2. zelyra db apply bringt das Produktivschema sicher auf den neuesten Stand.
  3. Klare Capability-Beschränkungen in zelyra.toml sichern den Server vor Angriffen ab.

7. Übungsaufgaben

8. Praxisaufgabe: Das produktionsfertige Aufgaben-Paket

Führe alle Einstellungen für das finale Deployment zusammen:

database main {
    engine: mariadb
    database: "tasks_production"
}

table tasks {
    id: Id primary auto
    name: String(100) required
    erledigt: Bool default false
}

page "/" {
    html {
        <html>
            <body>
                <h1>Aufgabenverwaltung - Produktivsystem</h1>
                <p>System bereit fuer Benutzeranfragen.</p>
            </body>
        </html>
    }
}

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welcher Befehl startet die Webanwendung auf einem Server?
  2. Warum sollte zelyra db apply vor dem Starten des Webservers ausgeführt werden?
  3. Welche Vorteile bietet der integrierte HTTP-Server gegenüber externen Server-Setups?

TEIL X – ABSCHLUSSPROJEKT UND WEITERFÜHRUNG

Kapitel 40: Das große Abschlussprojekt: Vollständige Aufgabenverwaltung

1. Was lerne ich in diesem Kapitel?

In diesem großen Finale lernst du:

2. Warum ist das Thema wichtig?

Einzelne Code-Snippets zu verstehen ist eine Sache – eine echte, zusammenhängende Anwendung aus einem Guss zu bauen, ist die eigentliche Kunst der Softwareentwicklung. Dieses Abschlussprojekt beweist die Eleganz von Zelyra: In einer einzigen, übersichtlichen Datei entsteht eine datenbankgestützte, authentifizierte Webanwendung mit UI und REST-API, für die man in herkömmlichen Frameworks dutzende Dateien anlegen müsste.

3. Verständliche Erklärung des Gesamtprojekts

Unsere Aufgabenverwaltung umfasst:

  1. Datenbank & Schemas: Ziel-Engine MariaDB mit Tabellen für Aufgaben (tasks), Benutzer (users), Sitzungen (auth_sessions) und Berechtigungen (user_permissions).
  2. Authentifizierung: auth users mit geschützten Routen und Argon2-Passwortschutz.
  3. Geschäftslogik: Reine Funktionen mit Verträgen (requires, ensures) zur Prioritätsprüfung und Fortschrittsberechnung.
  4. CRUD-Interface: Das administrative Web-Dashboard mit Listen, Formularen und Löschdialogen.
  5. REST-API: JSON-Endpunkte für den programmatischen Zugriff.

4. Das vollständige Projekt: Der finale Quelltext

database main {
    engine: mariadb
    database: "zelyra_tasks_app"
}

# ==========================================
# 1. AUTHENTIFIZIERUNG & BENUTZERVERWALTUNG
# ==========================================

auth users {
    table: users
    sessions: auth_sessions
    permissions: user_permissions
}

table users {
    id: Id primary auto
    email: Email required unique
    password_hash: String(255) required
    active: Bool default true
}

table auth_sessions {
    id: Id primary auto
    user: User required
    token_hash: String(64) required unique
    expires_at: Timestamp required
}

table user_permissions {
    id: Id primary auto
    user: User required
    permission: String(100) required
}

# ==========================================
# 2. AUFGABEN-DATENMODELL
# ==========================================

type TaskId = Id

table tasks {
    id: TaskId primary auto
    name: String(120) required
    beschreibung: String(500)
    prioritaet: Int default 2
    erledigt: Bool default false
}

# ==========================================
# 3. GESCHÄFTSLOGIK MIT VERTRÄGEN
# ==========================================

fn berechne_erfolgsquote(erledigte: Int, gesamt: Int) -> Int
    requires { gesamt > 0 && erledigte >= 0 && erledigte <= gesamt }
    ensures { result >= 0 && result <= 100 }
{
    return (erledigte * 100) / gesamt
}

fn prioritaet_label(stufe: Int) -> String {
    match stufe {
        1 => {
            return "HOCH"
        }
        2 => {
            return "MITTEL"
        }
        3 => {
            return "NIEDRIG"
        }
        _ => {
            return "NORMAL"
        }
    }
}

# ==========================================
# 4. WEBOBERFLÄCHE & CRUD-SCHNITTSTELLE
# ==========================================

crud Task -> tasks {
    title: "Zelyra Aufgabenverwaltung"

    view {
        fields {
            name
            prioritaet
            erledigt
        }

        list {
            mode: cards
            empty: "Keine Aufgaben vorhanden. Erstelle deine erste Aufgabe!"
        }

        detail {
            mode: cards
            title: "Aufgabendetails"
        }

        form {
            mode: cards
            title: "Aufgabe bearbeiten"
            submit: "Aufgabe sichern"
        }

        delete {
            title: "Aufgabe entfernen"
            message: "Moechtest du diese Aufgabe wirklich loeschen?"
            submit: "Jetzt loeschen"
        }
    }

    action abschliessen {
        label: "Als erledigt markieren"
        confirm: "Aufgabe abschliessen?"

        sql {
            UPDATE tasks
            SET erledigt = true
            WHERE id = :id
        }

        success "Aufgabe erfolgreich abgeschlossen."
        redirect "/tasks"
    }
}

# ==========================================
# 5. REST-API ENDPUNKTE
# ==========================================

api GET "/api/tasks/{id}" {
    input {
        id: TaskId
    }
    output Task
    errors {
        404 NotFound
    }
}

api POST "/api/tasks" {
    input {
        name: String
        prioritaet: Int
    }
    output Task
    errors {
        400 ValidationError
    }
}

# ==========================================
# 6. STARTSEITE
# ==========================================

page "/" {
    html {
        <html>
            <head>
                <title>Zelyra Aufgaben-System</title>
            </head>
            <body>
                <h1>Zelyra Aufgabenverwaltung</h1>
                <p>Das vollstaendige Abschlussprojekt ist einsatzbereit.</p>
                <a href="/tasks">Zur Aufgabenuebersicht</a>
            </body>
        </html>
    }
}

# ==========================================
# 7. EINSTIEGSPUNKT
# ==========================================

fn main() {
    print("Zelyra Aufgabenverwaltung vollstaendig initialisiert.")
}

5. Typische Fehler und deren Ursachen

6. Merksätze

  1. In Zelyra entsteht eine vollständige, sichere Web-App in einer einzigen, harmonischen Datei.
  2. Typsicherheit, Verträge, Authentifizierung und APIs greifen lückenlos ineinander.
  3. Dieser Code ist sofort mit zelyra check prüfbar und mit zelyra serve startbar.

7. Übungsaufgaben

8. Praxisaufgabe: Dein eigener produktiver Server-Start

Initialisiere das Projekt und starte es:

zelyra new task_manager --template minimal
cd task_manager
# Quellcode in src/main.zyl einfuegen
zelyra check src/main.zyl
zelyra serve src/main.zyl 0.0.0.0:8080

Öffne http://localhost:8080 – deine eigene Zelyra-Anwendung ist live!

9. Zusammenfassung

10. Kontrollfragen zur Selbstprüfung

  1. Welche Komponenten wurden im Abschlussprojekt kombiniert?
  2. Warum genügen in Zelyra so wenige Zeilen für ein vollwertiges CRUD-System?
  3. Welche Schritte sind erforderlich, um das Projekt auf einem neuen Server zu deployen?

Kapitel 41: Funktionsumfang und sicherer Betrieb

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Ein erfolgreich kompiliertes Programm kann fachliche Fehler enthalten. Ein erfolgreiches Schema-Update ersetzt kein Backup. Prüfe deshalb sowohl die konkrete Anwendung als auch ihren Datenbankpfad, bevor du einen neuen Stand übernimmst.

3. Aktueller Stand

Zelyra 1.2.39 ist das aktuelle stabile Release; die Sprachkompatibilitätslinie bleibt 0.1. MariaDB ist der breiteste geprüfte Laufzeitpfad. PostgreSQL und MySQL unterstützen ausgewählte Abläufe, aber nicht automatisch dieselben CRUD-, Authentifizierungs-, Mail- oder Wiederherstellungsfunktionen. Die Datenbankmatrix beschreibt die geprüften Pfade.

Seit 1.0.0 kamen hinzu: Compose-v2-Erkennung und ein reparierter Studio-Run-Einstieg (1.0.1); automatische lokale Tutorialdatenbank, Schema- und Beispieldateneinrichtung sowie for ... step und range (1.0.2); die erweiterte Standardbibliothek, |>-Pipelines, else if, freie Ports und wiederholbare Beispieldaten (1.0.3); eigene Compose-Projektnamen und isolierte Datenbankausweichpfade ohne Löschen alter Volumes (1.0.4); lokale Studio-Logs, sichere Deinstallation, reines Rechnungsdatum, serverseitige Rechnungsnummern, eine am Ablauf orientierte Tutorialstartseite und zweisprachige ausführliche Quellcodeanleitungen (1.0.5); das integrierte lokale UI- und Designsystem Zelyra UI mit compilergeprüften UI-Komponenten, Themes, Varianten, responsivem Layout, Charts und Browser-Druckansichten (1.0.6); typisierte wertliefernde if-Ausdrücke, funktionale Record-Updates (Customer { ..old, active: true }), lexikalische Lambdas in Pipelines (map, filter, find, reduce), verschachtelte Record-Muster und Match-Guards, First-Class-Tupel, Ausführungsbudgets (--max-steps), nominale Id-Aliase (type OrderId = Id), serverseitiges Text-PDF (render_pdf) und transaktionale PDF-Mail-Anhänge über die Outbox (1.0.7). Der Leitfaden erklärt, wie crud Invoice -> invoices die Ressource deklariert, aus der Zelyra Routen wie /invoices/new erzeugt. Vollständige Listen stehen in Anhang D und den Release-Notizen.

4. Rechnungstutorial in Studio

Erzeuge das Tutorial ohne separaten CLI-Start und öffne es im Editor:

zelyra --tutorial invoice --no-start
zelyra editor ./invoice-tutorial

Wähle main.zyl und klicke auf Run. Studio startet bei der lokalen .env-Konfiguration MariaDB über Docker Compose, richtet das Schema und die wiederholbaren Beispieldaten ein und startet die Webvorschau. MariaDB läuft im Container; die Webanwendung ist ein lokaler Zelyra-Prozess. Docker Compose v2 oder neuer ist erforderlich, Python Compose v1 wird nicht unterstützt. Mit docker compose version prüfst du das Plugin.

Bearbeite src/customers.zyl, src/items.zyl, src/invoices.zyl, src/dashboard.zyl oder src/shell.zyl im Projektbaum. zelyra.theme.css enthält lokale Gestaltungsregeln. Neue Geschäftsdaten gibst du über die Formulare ein; der Seed enthält nur wiederholbare Beispieldaten. Die Seite / führt durch den Rechnungsablauf; /views/invoicedashboard ist die Rechnungsübersicht. src/dashboard.zyl deklariert diese Übersicht. crud Invoice -> invoices erzeugt die Standardrouten einschließlich /invoices/new. Die zweisprachigen Dateien TUTORIAL.de.md und TUTORIAL.en.md erklären jeden Einrichtungsbefehl und seine Optionen, jede Quelldatei und deren einzelne Zeilen. Rechnungsdaten werden als Datum ohne Uhrzeit mit Format-Hinweis erfasst; die Rechnungsnummer vergibt der Server.

5. Installation und sichere Änderungen

Prüfe die installierte Version mit zelyra --version und die Umgebung mit zelyra doctor. Sichere Quellcode, Konfiguration und Datenbank vor Änderungen. Lies zelyra db plan main.zyl, bevor du db apply ausführst. Eine Rückwärtsmigration kann nachträglich geschriebene Daten entfernen; abgebrochenes DDL kann einen teilweise geänderten Zustand hinterlassen.

6. Release 1.0.7 und Details zum Tutorial

Die Release-Notizen 1.0.7 und die Roadmap unterscheiden veröffentlichte Funktionen von zukünftigen Vorhaben. Das Tutorial erklärt jeden Einrichtungsbefehl samt Optionen, beschreibt jede Quelldatei und erläutert ihre Quelltextzeilen. Insbesondere deklariert crud Invoice -> invoices in src/invoices.zyl eine Rechnungsressource. Zelyra leitet daraus und aus den Standardaktionen CRUD-Routen wie /invoices/new ab. Siehe die generierten Projektanleitungen TUTORIAL.de.md und TUTORIAL.en.md oder die Rechnungstutorial-Anleitung. Studio-Logs zeigen lokale Run- und Vorschauausgaben sowie Einrichtungsschritte. zelyra uninstall entfernt nach Bestätigung die aktive benutzereigene Programmdatei, lässt Projektdaten aber bestehen.

7. Typische Fehler

8. Praxisaufgabe: Änderungen vorbereiten

zelyra --version
zelyra doctor
zelyra check main.zyl
zelyra db plan main.zyl

Prüfe die Ausgabe. Erprobe Backup und Wiederherstellung in einer getrennten Testdatenbank, bevor du Schemaänderungen übernimmst.

9. Übungsaufgaben

10. Zusammenfassung

Zelyra 1.2.39 ist das aktuelle stabile Release. Das Rechnungstutorial startet MariaDB in Docker; die Webvorschau läuft als lokaler Zelyra-Prozess. Zelyra UI stellt lokal ausgelieferte, compilergeprüfte Komponenten bereit. Weitere Funktionen und ihre Grenzen sind oben, in den Release-Notizen und in der Datenbankmatrix beschrieben. Das CSV-Beispielpaket bietet explizite typisierte Konvertierungen, schreibt aber keine Datenbankdaten.

11. Kontrollfragen

  1. Was unterscheidet Compiler-Version und Sprachkompatibilitätslinie?
  2. Welche wichtigen Sprach- und Tutorialverbesserungen kamen in 1.0.3, 1.0.6 und 1.0.7 hinzu?
  3. Welche Tutorialkomponenten laufen in Docker, und welche bearbeitest du im Studio?
  4. Wie unterscheiden sich Release-Notizen und Roadmap?

Kapitel 42: Dein Weg als Zelyra-Entwickler

1. Was lerne ich in diesem Kapitel?

2. Warum ist das Thema wichtig?

Programmieren lernt man nicht durch bloßes Lesen, sondern durch Machen. Dieses Buch hat dir das Fundament vermittelt – jetzt beginnt deine persönliche Reise als Entwickler. Mit Zelyra besitzt du eine moderne, sichere und zukunftsfähige Sprache, die dich bei jedem Schritt unterstützt.

3. Die fünf goldenen Regeln für Zelyra-Entwickler

  1. Model First: Beginne jedes Projekt mit dem table-Schema. Ein klares Datenmodell löst die Hälfte aller späteren Probleme.
  2. Definiere Verträge: Sichere wichtige Funktionen mit requires und ensures ab. Sie sind Dokumentation und Test in einem.
  3. Rechte bewusst vergeben: Halte den Großteil deines Codes rein (ohne Capabilities) und deklariere Seiteneffekte gezielt.
  4. Fehler als Werte behandeln: Nutze Result und Option. Verbanne Ausreden für unkontrollierte Abstürze.
  5. Gemeinsam mit KI arbeiten: Nutze Zelyras --format json und Typed Holes _, um KI-Assistenten als produktive Co-Piloten einzusetzen.

4. Dein nächstes Projekt: Ideen zum Weiterprogrammieren

5. Übungsaufgaben

6. Zusammenfassung des Lehrbuchs

Herzlichen Glückwunsch! Du hast alle 10 Teile und 42 Kapitel von Zelyra lernen erfolgreich gemeistert. Du beherrschst die Grundlagen, das Typsystem, Fehlerbehandlung, Datenbanken, Webanwendungen, APIs und sichere Softwarearchitektur. Du bist jetzt bereit, eigene, robuste Anwendungen mit Zelyra zu erschaffen!

7. Kontrollfragen zum Abschluss

  1. Welche Zelyra-Besonderheit schätzt du nach diesem Lehrgang am meisten?
  2. Warum ist das Zusammenspiel von Sprache und Datenbank in Zelyra so revolutionär?
  3. Welches Projekt wirst du als Nächstes mit Zelyra umsetzen?

Kapitel 43: Mit Zelyra Studio arbeiten

1. Was lerne ich in diesem Kapitel?

2. Was ist Zelyra Studio?

Zelyra Studio ist der Webeditor, der mit dem Zelyra-CLI ausgeliefert wird. Er hilft dir, ein kleines Zelyra-Projekt an einem Ort zu öffnen, Quelltext zu bearbeiten, Compilerdiagnosen zu lesen und passende Datenbankinformationen nachzuschlagen. Du brauchst dafür keinen zusätzlichen Cloud-Editor und keinen externen KI-Dienst.

Studio ist ein Entwicklungswerkzeug für dein lokales Projekt. Es ist noch keine vollständige IDE und nimmt dir keine fachlichen Entscheidungen ab. Der erzeugte Quelltext bleibt normale Zelyra-Datei, die du auch außerhalb des Editors lesen, prüfen und versionieren kannst.

3. Studio starten

Wechsle in das Verzeichnis deines Projekts und starte den Editor:

cd maschinenverwaltung
zelyra editor

Für ein anderes Projekt kannst du den Ordner direkt angeben:

zelyra editor ./maschinenverwaltung

Das CLI öffnet den Standardbrowser und zeigt die lokale Adresse an. Auf SSH- oder Headless-Systemen startest du mit zelyra editor . --no-open und öffnest die angezeigte Adresse selbst. Zum Bearbeiten benötigt Studio keine laufende Datenbank. Studio bindet sich an 127.0.0.1; die Startadresse enthält ein zufälliges Sitzungstoken. Teile diese Adresse nicht öffentlich. Schreibende Browser-Anfragen benötigen das Token und müssen von derselben Browser-Origin kommen.

4. Dateien bearbeiten und prüfen

Der Projektbaum zeigt die Zelyra-Quelldateien. Öffne eine Datei in einem Tab, suche nach Text oder Symbolen, nutze die angezeigte Vervollständigung und formatiere den Quelltext bei Bedarf. Beim Speichern prüft Studio, ob die Datei seit dem Laden von einem anderen Programm verändert wurde. Bei einem Konflikt wird der fremde Stand nicht überschrieben; lade die Datei neu und prüfe die Änderungen.

Compilerdiagnosen erscheinen im Problems-Bereich und helfen dir, Fehler direkt im Editor zu finden. Der Aktionsfinder öffnet häufige Aktionen; die Kontexthilfe erklärt unterstützte Begriffe, Optionen und Beispiele. Strg+Leertaste bietet Vervollständigungen aus dem Compiler-Projektmodell und lokalen Bindungen, wenn der aktuelle Code geparst werden kann. F12 öffnet eine eindeutige Definition in der aktuellen oder direkt importierten Datei. Umschalt+F12 sucht lexikalisch gleiche Bezeichner in gespeicherten .zyl-Dateien, löst aber keine Gültigkeitsbereiche auf.

Die Projektkarte verbindet erkannte Module, Importe, Tabellen, TableViews, Views, CRUD-Ressourcen, Seiten, APIs und Funktionen mit Quellpositionen. Seiten- und CRUD-Layouts werden im eigenen Modul oder über ausdrücklich importierte öffentliche Views aufgelöst. Unklare und fehlende Beziehungen erhalten stabile Diagnosecodes. Mehrdeutige und dynamische Beziehungen werden nicht geraten; Größenbegrenzungen können die Karte unvollständig machen. Strg+S speichert den aktuellen Inhalt. Formatierung und Starten sind ausdrückliche Aktionen. Starten führt main.zyl höchstens 15 Sekunden aus und begrenzt jeden Ausgabekanal auf 64 KiB; erkannte Geheimnisse aus Umgebung und .env werden redigiert. Interaktive stdin-Eingabe ist nicht verfügbar. Speichern und Ausführen ändern keine weiteren Projektdateien stillschweigend.

Barrierefreiheit und Schriftgrößenskalierung

Für ermüdungsfreies Arbeiten und unterschiedliche Display-Anforderungen bietet Zelyra Studio eine integrierte dreistufige Schriftgrößenskalierung (Standard 100 %, Mittel +15 % und Groß +30 %):

5. Datenbankschema ansehen

Wähle im Studio Datenbank und lade das Schema. Dafür muss DATABASE_URL in der Umgebung oder in der lokalen Projektdatei .env verfügbar sein. Die Ansicht liest Tabellen- und Spaltenmetadaten sowie Beziehungen. Sie liest keine Geschäftsdatensätze und führt keine Schemaänderungen aus.

Die Karte zeigt Tabellen und Fremdschlüsselbeziehungen. Für den geprüften Umfang vergleicht sie deklarierte Tabellen und Spalten mit der Live-Datenbank und markiert Abweichungen. Eine Gruppierung nach Quelldatei hilft dir bei der Orientierung; sie vergibt keine Berechtigungen.

Die visuelle Schemaansicht ist für die geprüften MariaDB- und PostgreSQL-Pfade verfügbar. MySQL besitzt in dieser Version einen begrenzten parametrisierten Abfragepfad, aber keine Studio-Live-Introspektion. Die genaue Matrix steht in der Datenbankdokumentation.

Datenbrowser und Quellspalten bearbeiten

Der Datenbrowser lädt Datensätze erst auf ausdrücklichen Klick und zeigt höchstens 25 Zeilen je Seite. Er ist schreibgeschützt. Die Schemaansicht selbst liest nur Metadaten; ihr Öffnen lädt keine Geschäftsdatensätze.

Der Spaltenassistent ergänzt neue Quellfelder und bearbeitet einfache bestehende Felder. Schlüssel, eindeutige Felder und Felder mit Defaultwert sind von der visuellen Änderung ausgeschlossen. Studio zeigt Diff und Compilerdiagnosen und prüft vor der Übernahme erneut den Datei-Hash. Die Übernahme schreibt ausschließlich Quelltext. Prüfe danach zelyra db plan main.zyl und führe eine Datenbankänderung gesondert aus.

5a. Rechnungstutorial in Studio starten

Für den IDE-Arbeitsablauf erzeugst du zuerst die Dateien, ohne den separaten CLI-Start auszuführen:

zelyra --tutorial invoice --no-start
zelyra editor ./invoice-tutorial

Wähle im Projektbaum main.zyl und klicke auf Run. Bei der lokalen Tutorialkonfiguration in .env startet Studio MariaDB mit Docker Compose, wartet auf die Datenbank, wendet das deklarierte Schema an und lädt die wiederholbaren Beispieldaten. Anschließend startet Studio die Webvorschau und zeigt ihre Adresse an. Stop preview beendet die Vorschau.

Docker Engine und Docker Compose v2 oder neuer müssen installiert und für deinen Benutzer erreichbar sein. Python Compose v1 wird nicht unterstützt. Prüfe Compose mit docker compose version; Zelyra installiert Docker oder Compose nicht automatisch. Bei fehlendem Compose-Plugin findest du die Installationsanleitung unter Docker Engine für Linux.

In diesem Ablauf läuft MariaDB im Docker-Container. Die Webanwendung wird als lokaler Zelyra-Prozess gestartet; sie läuft nicht selbst in einem Anwendungscontainer. Externe oder per Prozessumgebung überschriebene Datenbankverbindungen startet Studio nicht und verändert sie nicht automatisch.

Das Tutorial enthält zwei Kunden, drei Artikel und den Rechnungsentwurf RE-2026-001 mit zwei Positionen. Wiederholte Starts duplizieren die markierten Beispieldaten nicht. Neue Kundinnen und Kunden, Artikel und Rechnungen legst du danach über die Formulare der Anwendung an.

5b. Rechnungstutorial bearbeiten

Bearbeite die Dateien im Projektbaum von Studio und speichere deine Änderungen:

Studio zeigt Compilerdiagnosen beim Bearbeiten. Wähle danach main.zyl und klicke erneut auf Run, um die lokale Vorschau mit der Änderung zu starten. Geschäftsdaten gibst du über die Oberfläche ein: /customers, /items und /invoices; die Rechnungsübersicht ist aktuell unter /views/invoicedashboard erreichbar.

/invoices/new wird nicht als eigene page-Route deklariert. Die Deklaration crud Invoice -> invoices in src/invoices.zyl erzeugt automatisch die CRUD-Routen für den Tabellenpfad invoices, darunter GET /invoices/new für das Formular und POST /invoices/new zum Speichern. Der Name rechts von -> bestimmt also den URL-Basispfad. Die Druckroute page "/invoices/{invoice_number}/print" ist dagegen ausdrücklich im Quelltext eingetragen. Mit zelyra routes main.zyl lässt sich die Herkunft prüfen: Die Ausgabe nennt Methode, Pfad, Routentyp sowie Quelldatei und Zeile; /invoices/new verweist so auf die CRUD-Deklaration.

Die Route /views/invoicedashboard ist eine durchsuchbare und filterbare Tabellenansicht von Rechnungen mit berechneten Netto-, Steuer- und Bruttosummen. Sie ist keine zweite Dashboard-Startseite. Die Startseite / zeigt derzeit Kennzahlen und führt durch den Tutorialablauf. Die Trennung und Gestaltung dieser Ansichten ist zur Überarbeitung für 1.0.5 vorgemerkt.

Wenn du zelyra update ausführst, während Studio geöffnet ist, beende die Sitzung mit Ctrl+C und starte Studio danach neu. Bereits laufende IDE-Sitzungen laden eine aktualisierte Programmdatei nicht automatisch nach.

Wenn beim Laden oder Speichern eines Kunden „The requested data could not be loaded“ erscheint, prüfe zuerst, ob die lokale Datenbank gestartet wurde und das Schema-Setup erfolgreich war. zelyra db create main.zyl gibt SQL zur Prüfung aus, erstellt aber selbst weder die Datenbank noch Tabellen.

6. CRUD-Quelltext geführt erzeugen

Wenn eine Tabelle im Zelyra-Projekt deklariert ist, auch live vorhanden ist und noch keine CRUD-Ressource hat, kannst du den Assistenten verwenden. Wähle die Quelldatei, einen Ressourcennamen, einen Titel und die sichtbaren Felder. Studio zeigt die betroffenen Datei-, Tabellen- und Beziehungsinformationen sowie die erzeugten Routen an.

Der Ablauf hat drei Schritte:

  1. Auswahl: Bestimme die deklarierte Tabelle, die Quelldatei und die sichtbaren Formularfelder.
  2. Code prüfen und Vorschau zeigen: Studio lässt den normalen Projektcompiler den Kandidaten prüfen und zeigt den erzeugten Quelltext, den Diff und mögliche Diagnosen.
  3. Änderung übernehmen: Erst nach deiner ausdrücklichen Bestätigung wird die geprüfte Datei geschrieben. Direkt davor prüft Studio erneut den Datei-Hash. Hat sich der Quelltext geändert, verlangt es eine neue Vorschau.

So kannst du sehen, welche Änderung der Assistent vorschlägt, bevor sie in deinem Projekt landet. Das Anwenden erzeugt Quelltext. Es migriert weder die Datenbank noch legt es Datensätze an oder löscht sie.

7. Ein einfacher Arbeitsablauf

Für eine kleine Kundenverwaltung kannst du so vorgehen:

  1. Lege ein Projekt mit einer deklarierten Tabelle an oder öffne dein bestehendes Projekt.
  2. Starte Studio und prüfe, ob die Datenbankverbindung erreichbar ist.
  3. Sieh dir Tabelle und Fremdschlüssel in der Datenbankkarte an.
  4. Erzeuge die CRUD-Ressource in der Vorschau und lies den Diff.
  5. Übernimm die Änderung erst, wenn Datei, Felder und Routen deinen Erwartungen entsprechen.
  6. Prüfe das Projekt erneut mit zelyra check main.zyl und starte es nach Bedarf mit zelyra run main.zyl.

Für Kunden, Artikel und Rechnungen kannst du stattdessen das geführte CLI-Tutorial mit zelyra --tutorial invoice starten. Es führt dich Schritt für Schritt durch diese zusammenhängende Anwendung.

Rechnungstutorial verwenden

Das Tutorial enthält mehrere Quelldateien und führt von Kunden und Artikeln zu Rechnungen und verknüpften Positionen. Das Dashboard zählt gespeicherte Kunden und Rechnungen. Netto, 19% Umsatzsteuer und Brutto ergeben sich aus Positionen; die Summen enthalten auch Entwürfe und sind keine gebuchte Umsatzstatistik. Die Druckansicht kann über den Browser als PDF gespeichert werden. Tabler Core 1.6.1 wird lokal als CSS ausgeliefert, ohne CDN oder externes JavaScript. Die Layout-Stile in zelyra.css sind für responsive Ansichten optimiert, sodass das Hauptinhalts-Grid auch auf schmaleren Bildschirmen die volle Arbeitsbreite nutzt und nicht in einer schmalen Randspalte zusammenfällt. Das Beispiel ist keine fachlich oder rechtlich abgenommene Rechnungsanwendung und enthält keine native PDF-Engine.

8. Grenzen und Sicherheit

9. Übungsaufgaben

10. Zusammenfassung

Studio bündelt Quelltextbearbeitung, Compilerfeedback, Schemaübersicht und eine geführte CRUD-Quelltextvorschau. Du behältst die Kontrolle über das ausdrückliche Anwenden; die Datenbankkarte bleibt lesend und der erzeugte CRUD-Code bleibt normaler Zelyra-Quelltext.

TECHNISCHES REFERENZHANDBUCH

1. Was Zelyra anders macht

In einer typischen Businessanwendung wird dieselbe Information mehrfach beschrieben: einmal in der Datenbank, noch einmal im Backend, erneut im Formular und schließlich in der API. Zelyra versucht, daraus eine einzige nachvollziehbare Kette zu machen:

Tabelle → Typen → SQL → Formulare → CRUD → Webseite → API/OpenAPI

Eine Spalte wie diese:

email: Email?

sagt bereits:

SQL bleibt dabei echtes SQL. Zelyra zwingt niemanden, einen anspruchsvollen JOIN in eine 38 Glieder lange Methodenkette zu verwandeln. SQL hat schon genug erlebt.

2. Installation

Voraussetzungen

Für Sprachbeispiele genügen:

MariaDB wird erst für Datenbank-, Formularaktions-, Auth- und CRUD-Beispiele benötigt.

Aus dem Repository installieren

git clone https://github.com/sf1976/zelyra.git
cd zelyra
./install.sh

Der Installer ist wiederholbar und benutzerlokal. Optionen zur Kontrolle:

./install.sh --help
./install.sh --dry-run --root "$HOME/.local"
./install.sh --check
./install.sh --uninstall

Mit --no-rustup wird die automatische Rust-Installation deaktiviert, --no-path unterdrückt PATH-Hinweise. Mit --root PATH oder ZELYRA_INSTALL_ROOT lässt sich ein anderes benutzerbezogenes Ziel wählen. Veraltete cargo-PATH-Einträge werden erkannt und nicht blind ausgeführt.

Veröffentlichte Releases für Linux x86_64 und Windows x86_64 können ohne Rust oder Cargo installiert werden. Das gewählte Archiv wird über HTTPS geladen und per SHA-256 geprüft:

./install.sh --release v1.0.5

Unter Windows steht install.ps1 für PowerShell und install.cmd für die Eingabeaufforderung bereit:

git clone https://github.com/sf1976/zelyra.git
Set-Location zelyra
.\install.ps1
zelyra --version

Das Release-Archiv unter Windows:

.\install.ps1 -Release v1.0.5

Danach:

zelyra --version
zelyra --help

Wenn die Shell zelyra nicht findet:

export PATH="$HOME/.local/bin:$PATH"

Docker und Container-Umgebung

Zelyra installiert Docker selbst nicht, verändert keine Betriebssystempakete und fordert keine Root-Rechte an. Für Container- und MariaDB-Workflows wird Docker mit Compose-Unterstützung benötigt:

Überprüfe die Docker-Umgebung vor dem ersten Start:

docker compose version

Ist Docker installiert, aber der Zugriff auf seinen Socket verweigert, meldet Zelyra einen sicheren Hinweis zur Linux-Gruppenmitgliedschaft (sudo usermod -aG docker $USER) statt der rohen Docker-Ausgabe. Auch Portkonflikte werden ohne Preisgabe von Zugangsdaten gemeldet.

Zelyra aktualisieren

Ein Update besteht aus zwei getrennten Teilen: Du aktualisierst den Zelyra- Compiler im Compiler-Repository und prüfst danach dein eigenes Anwendungsprojekt. Deine .zyl-Dateien, zelyra.toml und .env liegen in deinem Anwendungsprojekt und werden durch install.sh nicht überschrieben.

Installation aus dem Git-Repository

Arbeite zuerst im Compiler-Repository. Prüfe lokale Änderungen, bevor du sie aktualisierst:

cd /pfad/zu/zelyra
git status --short
git pull --ff-only origin main
cargo check --workspace
./install.sh
zelyra doctor /pfad/zu/deinem-projekt/main.zyl --json

git pull --ff-only bricht ab, wenn du lokale Änderungen oder eine eigene Historie hast. Sichere oder committe diese Änderungen zuerst und führe das Update danach erneut aus. ./install.sh baut die aktuelle CLI-Version und installiert sie mit cargo install --path cli --force erneut in deinem Benutzerverzeichnis.

Die installierte Versionsnummer kannst du über zelyra --version oder den JSON-Bericht von doctor ablesen:

zelyra --version
zelyra doctor /pfad/zu/deinem-projekt/main.zyl --json

3. Das erste Programm

Datei hello.zyl:

fn main() {
    print("Hallo von Zelyra")
}

Ausführen:

zelyra run hello.zyl

Ausgabe:

Hallo von Zelyra

Ein etwas ehrgeizigeres Beispiel:

fn fibonacci(n: Int) -> Int {
    if n <= 1 {
        return n
    }

    return fibonacci(n - 1) + fibonacci(n - 2)
}

fn main() {
    print(fibonacci(10))
}

Ergebnis: 55. Der Rechner hat es geschafft. Wir dürfen fortfahren.

4. Neues Projekt anlegen und CLI

Compiler-Repository und Anwendungsprojekt

Das GitHub-Repository sf1976/zelyra ist das Compiler-Repository. Es enthält Lexer, Parser, Runtime, Datenbank- und Webmodule sowie das CLI. Eine eigene Anwendung ist ein davon getrenntes Verzeichnis. Du musst also nicht in der Zelyra-Quelle arbeiten und solltest dort auch keine Zugangsdaten ablegen.

Der Projektstamm ist das Verzeichnis, in dem die Zelyra-Quelldatei und – wenn vorhanden – zelyra.toml liegen. Der Speicherort ist frei wählbar, zum Beispiel ~/projekte/adressverwaltung oder C:\\Users\\Du\\Projekte\\adressverwaltung.

✅ Projekt mit dem vorhandenen CLI anlegen

Voraussetzungen für die CLI-Installation sind Rust/Cargo oder ein Release-Archiv; für relationale Datenbankbefehle der externe mariadb-Client oder Docker. Das CLI bietet aktuell diese Projektbefehle:

zelyra new adressverwaltung
cd adressverwaltung
zelyra run main.zyl

Ein vorhandenes Verzeichnis initialisieren:

mkdir adressverwaltung
cd adressverwaltung
zelyra init

Für eine lokale MariaDB- und Webserver-Vorlage zelyra new maschinenverwaltung --mariadb verwenden:

zelyra new maschinenverwaltung --mariadb
cd maschinenverwaltung

Dadurch entstehen main.zyl, .env.example, Dockerfile und docker-compose.mariadb.yml sowie direkt eine geschützte .env mit sicheren Zufallspasswörtern.

Automatische Portvergabe bei Konflikten: Sind die Standardports 3000 (Web) oder 3306 (MariaDB) auf dem Rechner belegt, ermitteln zelyra new, zelyra init und zelyra setup automatisch den nächsten freien Host-Port und tragen ihn in die neue .env ein. Mit den optionalen Flags --web-port <p>, --host-port <p> und --db-host-port <p> können Ports verbindlich vorgegeben werden.

✅ Zelyra-Setup-Assistent (Konsole und Browser)

zelyra setup bietet konsistente Einrichtungsaktionen sowohl über die Befehlszeile als auch über eine benutzerfreundliche Weboberfläche:

Setup auf der Konsole

Aus einem MariaDB-Projektverzeichnis:

zelyra setup
zelyra setup --database
zelyra setup --schema
zelyra setup --all
zelyra setup --host-port 18080 --db-host-port 3308

Wähle den Projekttyp vor dem Setup:

Projektpfade sind relativ oder absolut, nicht austauschbar:

zelyra setup ./test_a
zelyra setup /test_a

Der erste Aufruf sucht ein Unterverzeichnis des aktuellen Ordners, der zweite das Verzeichnis /test_a im Wurzelverzeichnis. Existiert der angegebene Pfad nicht, meldet Zelyra E-SETUP-001; wenn ein gleichnamiges relatives Verzeichnis existiert, schlägt die Meldung den passenden relativen Aufruf vor.

Setup im lokalen Browser (zelyra setup --web)

zelyra setup --web

Der Assistent bindet standardmäßig ausschließlich an 127.0.0.1:3030 und erzeugt eine sichere, einmalige URL mit einem Zufallstoken:

Zelyra setup web is running on http://127.0.0.1:3030/
open: http://127.0.0.1:3030/?token=<local-token>

Nach dem Start prüft zelyra doctor den Status ohne destruktive Datenbankänderungen:

zelyra doctor main.zyl --env-file .env

Für ein vollständiges CRUD-Starterprojekt mit Geschäftslogik:

zelyra new maschinenverwaltung --template mariadb-crud
cd maschinenverwaltung
zelyra setup --all

Prüfen, ausführen, formatieren und verifizieren

Das dokumentierte, benutzerseitige Kommandozeilenprogramm heißt zelyra. Mit zelyra check <file.zyl> prüfst du Syntax, Typen, Verträge und Capabilities, bevor du ein Programm mit zelyra run <file.zyl> ausführst. zelyra fmt <file.zyl> formatiert den Quelltext; --check prüft die Formatierung, ohne die Datei zu ändern. zelyra verify <file.zyl> führt die unterstützten Vertrags- und Invariantenprüfungen aus.

Die aktuelle CLI-Referenz führt keinen Unterbefehl zelyra test auf. Projektbezogene Testroutinen kannst du in einer ausführbaren Quelldatei ablegen und mit zelyra run starten; assertionsbasierte Prüfungen beschreibt Kapitel 19. Ebenso dokumentiert die Referenz kein separates Programm zelyrac build: Der Compiler wird über zelyra check und zelyra run aufgerufen.

LSP steht für Language Server Protocol und bezeichnet den Standard für die Kommunikation zwischen Editor und Sprachserver. Der dokumentierte Einstieg in den Editor ist zelyra editor, das Studio lokal startet. Einen separaten Unterbefehl zelyra lsp führt die aktuelle CLI-Referenz nicht auf.

5. Variablen, Typen und Funktionen

Werte sind standardmäßig unveränderlich:

machine_name = "Presse 7"
capacity: Int = 120
active = true

Veränderung muss sichtbar sein:

mutable completed = 0
completed = completed + 1

Das verhindert versehentliche Änderungen. Der Compiler ist dabei nicht misstrauisch; er hat nur schon Dinge gesehen.

Wichtige Typen:

Int UInt Float Decimal Bool String Char Bytes
Timestamp Date Time Duration Email Url Uuid Money

Funktionen:

fn available_capacity(total: Int, reserved: Int) -> Int {
    return total - reserved
}

Typnamen dokumentieren die fachliche Bedeutung von IDs:

type MachineId = Id
type OrderId = Id

Diese Aliase besitzen keine eigene Runtimeidentität. Prüfe ID-Zuordnungen und Mandantengrenzen in der Geschäftslogik; die Bezeichnung allein beweist keinen Zugriffsschutz.

6. Option, Result und Pattern Matching

Normale Typen sind nicht null. Ein möglicher fehlender Wert wird markiert:

email: Email?

Behandlung:

match email {
    Some(value) => print(value)
    None => print("Keine E-Mail hinterlegt")
}

Pattern Matching muss vollständig sein. Sonst erinnert dich der Compiler an den Fall, den der Freitagabend-Deploy vermutlich gefunden hätte.

Fehler werden als Teil der Funktionssignatur sichtbar. Der aktuelle Sprachkern verwendet dafür Result<T, E> mit Ok oder Err:

fn load_number(found: Bool) -> Result<Int, String> {
    if found {
        return Ok(42)
    }
    return Err("nicht gefunden")
}

7. MariaDB und Tabellen

✅ MariaDB ist das Standardbackend und die primäre Runtime-Referenz. Die generierte Compose-Vorlage verwendet mariadb:11; der Compiler erzwingt aber keine konkrete MariaDB-Serverversion. Die Datenbankbefehle rufen den externen mariadb-Client auf.

database main {
    engine: mariadb
}

table departments {
    id: Id primary auto
    name: String(100) required unique
}

table machines {
    id: Id primary auto
    number: String(30) required unique
    name: String(100) required
    department: Department required
    active: Bool default true
}

Zelyra erkennt die Beziehung zwischen Maschine und Abteilung. Daraus können Foreign Keys, Formulare und Auswahlfelder entstehen.

Typische Abbildung:

Zelyra MariaDB
Id primary auto automatisch vergebene Primär-ID
String(100) VARCHAR(100)
String TEXT
Email E-Mail-kompatible Textspalte
Bool boolescher Datenbankwert
Timestamp Zeitstempelwert

MariaDB sicher vorbereiten

Lege für die Anwendung eine eigene Datenbank und einen eigenen Benutzer an. Verwende nicht den MariaDB-Account root für den laufenden Zelyra-Webserver. Die folgenden Befehle werden als administrativer MariaDB-Benutzer ausgeführt; das Passwort wird interaktiv abgefragt:

mariadb --host=127.0.0.1 --port=3307 --user=root --password

CREATE DATABASE `adressverwaltung`
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;

CREATE USER 'zelyra'@'127.0.0.1'
    IDENTIFIED BY 'HIER_LOKALES_PASSWORT_EINTRAGEN';

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, REFERENCES
    ON `adressverwaltung`.* TO 'zelyra'@'127.0.0.1';

SHOW GRANTS FOR 'zelyra'@'127.0.0.1';

CREATE DATABASE kann bei einer bereits vorhandenen Datenbank mit IF NOT EXISTS wiederholbar gemacht werden. Die Rechte sind bewusst auf diese Datenbank begrenzt; GRANT ALL ON *.* gehört nicht in einen Anwendungs- Schnellstart. InnoDB ist die für Transaktionen und Fremdschlüssel erwartete Storage-Engine. Die aktuelle Zelyra-SQL-Ausgabe setzt ENGINE=InnoDB jedoch nicht selbst; kontrolliere und ergänze das SQL vor dem Anwenden, wenn deine Servervorgaben es verlangen.

Für reine Lese- und normale CRUD-Operationen reichen die aufgeführten Rechte. db apply --allow-destructive kann zusätzlich DROP-Rechte benötigen; erteile sie nur bewusst und möglichst zeitlich begrenzt. db setup ist ein Administratorvorgang, weil dabei die Datenbank selbst angelegt wird.

Lokal kann MariaDB bereits auf Port 3306 laufen. Die generierte Compose-Datei veröffentlicht standardmäßig 127.0.0.1:3306. Wenn dieser Port belegt ist, ändere die Zuordnung auf 127.0.0.1:3307:3306: außen ist dann 3307, im Container bleibt MariaDB auf 3306. Von einem anderen Compose-Service ist der Host der Servicename mariadb und der Port weiterhin 3306; vom Host ist es 127.0.0.1 plus der veröffentlichte Port.

Das Adressschema kontrollieren

Für das Beispiel erzeugt zelyra db create src/main.zyl derzeit sinngemäß:

CREATE TABLE IF NOT EXISTS `addresses` (
    `id` BIGINT PRIMARY KEY NOT NULL AUTO_INCREMENT,
    `first_name` VARCHAR(100) NOT NULL,
    `last_name` VARCHAR(100) NOT NULL,
    `street` VARCHAR(150) NOT NULL,
    `postal_code` VARCHAR(10) NOT NULL,
    `city` VARCHAR(100) NOT NULL,
    `email` VARCHAR(255)
) ENGINE=InnoDB DEFAULT CHARACTER SET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Für MariaDB enthalten die erzeugten Tabellenaussagen ENGINE=InnoDB DEFAULT CHARACTER SET=utf8mb4 COLLATE=utf8mb4_unicode_ci. Damit sind sie für die dokumentierte MariaDB-Basis vollständig; sie bleiben dennoch ein zu prüfender Schema-Vorschlag. Vor Änderungen an einer bestehenden Datenbank weiterhin db plan lesen und das Risiko ausdrücklich bewerten.

Weitere Datenbank-Backends

Neben MariaDB kann das Schema-CLI derzeit auch SQLite und PostgreSQL verarbeiten. Das Backend wird in der .zyl-Datei angegeben:

database main { engine: sqlite database: "adressverwaltung.sqlite3" }
database main { engine: postgres database: "adressverwaltung" }

Für SQLite verwendet DATABASE_URL das Schema sqlite:// oder sqlite:; für MariaDB sind mariadb:// und der kompatible Name mysql:// gültig. Die Schemaoperationen create, inspect, plan und apply berücksichtigen Tabellen, Spalten, Foreign Keys und Indizes. db setup und db bootstrap unterstützen für das automatische Anlegen derzeit MariaDB und SQLite; für PostgreSQL verwendest du das gewünschte Schema mit db create, db inspect, db plan und anschließend db apply.

export DATABASE_URL='sqlite:///tmp/adressverwaltung.sqlite3'
zelyra db bootstrap src/main.zyl
zelyra db inspect src/main.zyl

Die native SQL-Runtime wird weiterhin hauptsächlich mit MariaDB eingesetzt. Ein vorhandenes Schema-Backend ist daher nicht automatisch ein Beleg dafür, dass jede Runtime-Abfrage mit jedem Backend gleich funktioniert.

8. Schema prüfen und anwenden

Zelyra verwendet keine Migrationsklassen. Die Quelldatei ist das gewünschte Schema; das CLI vergleicht dieses mit dem Ist-Zustand. Der aktuelle Ablauf ist:

  1. Quelldatei prüfen: zelyra check src/main.zyl.
  2. SQL nur anzeigen: zelyra db create src/main.zyl.
  3. Ist-Schema lesen: zelyra db inspect src/main.zyl.
  4. Unterschied planen: zelyra db plan src/main.zyl.
  5. Plan lesen und Risiko bewerten.
  6. Nach der Kontrolle anwenden: zelyra db apply src/main.zyl.

Die Verbindung kommt ausschließlich aus der Prozessumgebung:

export DATABASE_URL='mariadb://zelyra:HIER_LOKALES_PASSWORT_EINTRAGEN@127.0.0.1:3307/adressverwaltung'

⚠️ Zelyra lädt .env derzeit nicht automatisch. Eine .env ist eine sichere lokale Ablage, aber die Variablen müssen vor dem CLI-Aufruf in die Prozessumgebung gelangen. Siehe Abschnitt 16.

Schema-SQL anzeigen:

zelyra db create src/main.zyl > sql/addresses.generated.sql

Wenn du diese Datei nach der Kontrolle manuell um ENGINE=InnoDB und die Zeichensatzklauseln ergänzt hast, wendest du genau diese Datei mit dem MariaDB-Client an:

mariadb --host=127.0.0.1 --port=3307 --user=zelyra --password \
    adressverwaltung < sql/addresses.generated.sql

zelyra db apply liest keine von dir bearbeitete SQL-Datei ein; es erzeugt seinen Plan erneut aus der .zyl-Quelle. Verwende deshalb entweder den unveränderten Zelyra-Plan oder den manuellen Clientweg – nicht beides blind hintereinander.

Bedingt durch die aktuelle Implementierung kann db plan auch ohne DATABASE_URL gegen ein leeres Schema planen. Für eine echte Bestandsaufnahme und für db apply ist die Variable Pflicht:

zelyra db inspect src/main.zyl
zelyra db plan src/main.zyl
zelyra db apply src/main.zyl

Destruktive Änderungen werden abgelehnt, bis sie ausdrücklich freigegeben werden:

zelyra db apply src/main.zyl --allow-destructive

Dieses Flag bedeutet nicht „wird schon gutgehen“. Es bedeutet „ich habe den Plan gelesen, ein Backup und einen vernünftigen Puls“.

db setup und sein Alias db bootstrap versuchen bei MariaDB zuerst die Datenbank anzulegen und wenden anschließend das generierte Schema an. Dafür braucht DATABASE_URL administrative Rechte. Ein gewöhnlicher Anwendungsbenutzer mit begrenzten Rechten sollte stattdessen db create verwenden und die SQL-Schritte durch einen Administrator ausführen lassen.

❌ Nicht vorhanden sind zelyra db check sowie zelyra schema inspect, zelyra schema plan und zelyra schema apply. Der tatsächlich vorhandene Bereitschaftstest ist zelyra doctor src/main.zyl; er prüft statische Regeln, Cargo, DATABASE_URL (wenn gesetzt) und den lokalen Webport.

In 10 Minuten zur ersten Zelyra-Anwendung

Die folgenden Schritte verwenden überall dieselben Werte: das Verzeichnis adressverwaltung, die Datei src/main.zyl, die Datenbank adressverwaltung, den Benutzer zelyra und den Host-Port 3307.

  1. Projektverzeichnis und Vorlage anlegen:

    zelyra new adressverwaltung --mariadb
cd adressverwaltung
cp .env.example .env

  2. In .env die Platzhalter setzen. Wichtig: Compose liest die MARIADB_*-Werte beim Containerstart; Zelyra selbst liest nur DATABASE_URL. Ändere für den Host-Port in der Compose-Datei die Bindung auf 127.0.0.1:3307:3306 und verwende lokal 3307.

  3. MariaDB starten:

    docker compose -f docker-compose.mariadb.yml up -d mariadb
docker compose -f docker-compose.mariadb.yml ps

  4. Als MariaDB-Administrator Datenbank und Benutzer vorbereiten; verwende das SQL aus Abschnitt 7 und nur ein lokales Platzhalterpasswort.

  5. Die gültige Adressverwaltung als src/main.zyl speichern und prüfen:

    zelyra check src/main.zyl

  6. Die URL in die Prozessumgebung laden und die Verbindung testen. .env wird von Zelyra nicht automatisch geladen:

    set -a
. ./.env
set +a
zelyra doctor src/main.zyl --json

  7. Das gewünschte SQL erzeugen und vor dem Einsatz lesen:

    zelyra db create src/main.zyl > sql/addresses.generated.sql
sed -n '1,160p' sql/addresses.generated.sql

  8. Ist-Schema und Plan ansehen:

    zelyra db inspect src/main.zyl
zelyra db plan src/main.zyl

  9. Nach manueller Prüfung anwenden:

    zelyra db apply src/main.zyl

  10. Eine Webanwendung starten. Für eine CRUD-Route braucht die Quelldatei zusätzlich eine vom Server akzeptierte Webdefinition; crud allein ist noch kein statischer Export:

    zelyra serve src/main.zyl 127.0.0.1:3000

Unter Windows ersetze cp durch Copy-Item und lade Variablen beispielsweise so in PowerShell:

Copy-Item .env.example .env
$env:DATABASE_URL = 'mariadb://zelyra:HIER_LOKALES_PASSWORT_EINTRAGEN@127.0.0.1:3307/adressverwaltung'
zelyra doctor src/main.zyl --json

Der Generator bindet in der ausgelieferten Compose-Vorlage standardmäßig Port 3306; 3307 ist dieses Handbuchs ein bewusst gewählter, kollisionsarmer Host-Port. Passe die Compose-Portzeile an, bevor du den Schnellstart kopierst.

9. Natives SQL

✅ SQL ist ein Sprachelement:

fn load_active_machines() -> Machine[]
    uses Database
{
    return sql<Machine[]> {
        SELECT id, number, name, department_id, active
        FROM machines
        WHERE active = true
        ORDER BY number
    }
}

Parameter werden benannt und sicher gebunden:

fn load_machine(id: MachineId) -> Machine?
    uses Database
{
    return sql<Machine?> {
        SELECT id, number, name, department_id, active
        FROM machines
        WHERE id = :id
    }
}

Zelyra prüft, soweit das Schema bekannt ist:

Schreibzugriff in einer Transaktion:

transaction {
    sql {
        UPDATE machines
        SET active = false
        WHERE id = :id
    }
}

10. Webseiten

✅ Eine vollständige, sichere Webschicht mit typisierten Datenbindungen, Query-Steuerungen und Komponenten ist implementiert.

page "/machines/{name}" {
    html {
        <html>
            <body>
                <h1>Maschine {name}</h1>
                <p>Sie läuft. Hoffentlich nicht weg.</p>
            </body>
        </html>
    }
}

Start:

zelyra serve app.zyl

Dann beispielsweise:

http://127.0.0.1:3000/machines/Presse-7

Pfadwerte werden standardmäßig HTML-escaped. Der derzeitige Web Core umfasst GET-Routen, Pfadparameter, Query-String-Behandlung, HTTP-Parsing und HTML-Antworten.

Typisierte Datenbindung und Collections in Views

View-Interpolationen werden vor dem Serverstart statisch validiert. Eine Seite kann Routenparameter nutzen, geladene Datensätze über typisiertes SQL abrufen und auf deren Felder geprüft zugreifen:

page "/customers/{name}" {
    load customer = sql<Customer> {
        SELECT id, name FROM customers WHERE name = :name
    }
    html { <h1>{customer.name}</h1> }
}

SQL wird gegen das Schema geprüft, Parameter werden sicher gebunden und Capabilities sowie Berechtigungen vorab erzwungen. Collections können mit einer typisierten serverseitigen Schleife gerendert werden:

page "/customers" {
    load customers = sql<Customer[]> { SELECT id, name FROM customers }
    html { <ul>for customer in customers { <li>{customer.name}</li> }</ul> }
}

Deklarative Query-Steuerungen: Suche, Sortierung, Pagination und Filter

Seiten können typisierte Query-Eingaben für ausdrückliches SQL deklarieren:

page "/customers" {
    input { search: String? }

    load customers = sql<Customer[]> {
        SELECT id, name FROM customers
        WHERE (:search IS NULL OR name LIKE CONCAT('%', :search, '%'))
        ORDER BY name
    }

    html { <p>Suche: {search}</p> }
}

Für Page-Collections, die Suche, Filterung, Sortierung oder Pagination deklarieren, erzeugt Zelyra automatisch semantische Formulare und bewahrt den URL-Zustand:

page "/customers" {
    search { name email }
    sort { name }
    paginated 25
    filter { name quantity }
    load customers = sql<Customer[]> { SELECT id, name, quantity FROM customers }
    html {
        <p>Seite: {page} von {pages} (Gesamt: {total})</p>
        <p>Sortierung: {sort} ({order})</p>
    }
}

Benannte Views und Komponenten

Ein benannter View bietet ein wiederverwendbares Seiten-Layout. Er deklariert Slots, in die Seiteninhalte eingefügt werden:

view SiteShell {
    html {
        <html><body><main><slot /></main></body></html>
    }
}

page "/customers" {
    view: SiteShell
    html { <h1>Customers</h1> }
}

Typisierte Komponenten deklarieren Eigenschaften mit props:

component Badge {
    props { text: String }
    html { <span class="badge">{text}</span> }
}

page "/status" {
    html { <Badge text="Ready" /> }
}

Komponenten unterstützen Default-Slots und benannte Slots mit Fallback-Inhalten:

component Panel {
    html {
        <section class="panel">
            <header><slot name="header">Standard-Kopfzeile</slot></header>
            <div class="body"><slot /></div>
        </section>
    }
}

page "/dashboard" {
    html {
        <Panel>
            <slot name="header"><h1>Mein Dashboard</h1></slot>
            <p>Hauptinhalt des Panels.</p>
        </Panel>
    }
}

Hinweis: Verschachtelte Komponenten-Slots innerhalb einer Komponentenverwendung benötigen nicht fälschlich ein übergeordnetes Seiten-view:-Layout.

11. Formulare

✅ Formulare können Regeln aus Tabellen übernehmen:

form MachineCreate -> machines {
    fields {
        number
        name
        department
        active
    }
}

Explizite Definition:

form ContactForm {
    field email: Email {
        label: "E-Mail"
        required
        max: 255
        widget: email
    }
}

Werte ohne Server prüfen:

zelyra form validate examples/customer_form.zyl CustomerCreate \
    name="Muster GmbH" email=info@example.test

Mit zelyra serve stellt Zelyra das Formular unter /forms/FormName bereit. GET rendert das Formular samt CSRF-Token; POST prüft Token und Werte.

Eine Aktion:

form CustomerCreate -> customers {
    fields { name email }

    action save {
        requires auth
        permits "customers.save"
        sql {
            INSERT INTO customers (name, email)
            VALUES (:name, :email)
        }

        redirect "/customers"
    }
}

Formularaktionen können eine eigene Autorisierung deklarieren. Die Berechtigung wird beim Anzeigen des Formulars und erneut vor dem Absenden geprüft.

12. CRUD

✅ Der kurze Fall ist erfreulich kurz:

crud Machine -> machines

Konfiguriert:

crud Machine -> machines {
    title: "Maschinen"
    list { number name department active }
    search { number name }
    filter { department active }
}

Zelyra stellt Listen, Details, Create/Edit-Formulare, Suche, Filter, Sortierung, Pagination und eine CSRF-geschützte Löschaktion bereit. Spalten werden gegen das Schema geprüft.

Beispiele für URLs:

/machines
/machines?search=Presse
/machines?filter_active=true
/machines?sort=number&order=asc
/machines/new
/machines/42/edit

CRUD-Ressourcen mit wiederverwendbaren View-Layouts (layout: ViewName)

CRUD-Definitionen können über das Attribut layout: ViewName in das globale Seitenlayout eingebunden werden:

view AppLayout {
    html {
        <html>
            <head><title><slot name="title">Verwaltung</slot></title></head>
            <body>
                <nav><slot name="nav">Standard-Navigation</slot></nav>
                <main><slot name="content" /></main>
                <aside><slot name="actions" /></aside>
            </body>
        </html>
    }
}

crud Machine {
    table machines
    layout: AppLayout
}

Das System befüllt die benannten Slots title, nav, content und actions automatisch mit den generierten CRUD-Ansichten.

Erzeugte CRUD- und Tableview-Steuerungen verwenden semantische Fieldsets und getrennte Beschriftungen für Operator und Wert jedes Filters. Filterverarbeitung und bewahrte Pagination-URLs verwenden eine deterministische Reihenfolge.

🗺️ Vollständig eigene typisierte Komponenten und feingranulare View-Overrides sind Teil der weiteren View-Roadmap.

CRUD-Ansichten, Aktionen und Soft Delete

🧪 Die aktuelle CRUD-Schicht lässt sich innerhalb der sicheren Standardpfade gezielt anpassen. Eine Listenansicht kann beispielsweise als Kartenansicht erscheinen, ohne Suche, Filter, Sortierung, Pagination, Escaping oder Berechtigungsprüfung zu verlieren:

crud Customer -> customers {
    view {
        list {
            mode: cards
            empty: "Keine Kunden gefunden."
        }
        detail {
            mode: cards
            title: "Kundendetails"
        }
        form {
            mode: cards
            title: "Kundenformular"
            submit: "Kunden speichern"
        }
        delete {
            title: "Kunden löschen"
            message: "Dieser Vorgang kann nicht rückgängig gemacht werden."
            submit: "Jetzt löschen"
        }
        loading { message: "Kunden werden geladen ..." }
        error {
            title: "Kunden nicht verfügbar"
            message: "Bitte später erneut versuchen."
        }
    }
}

Für den häufigen Fall kann ein gemeinsames Feldprofil die erzeugte Liste, Detailansicht sowie Create-/Edit-Formulare einheitlich steuern:

crud Customer -> customers {
    view {
        fields { name email active }
    }
}

Ein explizites list { ... } bleibt eine Überschreibung für Liste/Detail. Primärschlüssel und automatisch erzeugte Felder bleiben in Formularen automatisch ausgeschlossen; unbekannte Profilfelder weist der Compiler zurück. Wenn die technische id-Spalte in fields ausgeblendet ist (wie im obigen Beispiel mit name email active), verlinkt Zelyra in generierten CRUD-Listen automatisch das erste angezeigte Feld (name) mit der Detailseite des Datensatzes. Das gilt sowohl für Tabellen- als auch für Kachel-Layouts.

Eigene fachliche Aktionen bleiben POST-only, parametrisiert und geschützt. Eine Action kann mehrere SQL-Anweisungen bündeln, die in einer gemeinsamen MariaDB-Transaktion atomar ausgeführt werden:

crud Invoice -> invoices {
    action lock {
        label: "Festschreiben (GoBD)"
        confirm: "Möchten Sie diese Rechnung unwiderruflich festschreiben?"
        permits "invoices.lock"
        field reason: String required
        sql {
            UPDATE invoices SET is_locked = true WHERE id = :id
            INSERT INTO invoice_audit_logs (invoice_id, action, message) VALUES (:id, "locked", :reason)
        }
        success "Rechnung wurde festgeschrieben."
        redirect "/invoices"
    }
}

Ausführungsmodell und Transaktionsverhalten von Actions

Die Laufzeit erzwingt für solche Aktionen Datenbank-Capability, CSRF-Schutz, Authentifizierung und die deklarierte Berechtigung. Aktionen können zusätzlich typisierte Felder, eine Bestätigungsseite sowie eigene Erfolgs- und Fehlerseiten erhalten. Das ist eine Erweiterung der vorhandenen CRUD-Runtime, kein frei programmierbarer Frontend-Generator.

Für reversible Löschungen gibt es eine Soft-Delete-Konfiguration:

table customers {
    id: Id primary auto
    name: String(100) required
    deleted_at: Timestamp?
}

crud Customer -> customers {
    soft_delete { column: deleted_at }
}

Normale Listen und Details zeigen nur Zeilen mit NULL; archivierte Datensätze sind über ?archived=true erreichbar und können über eine CSRF-geschützte Restore-Aktion wiederhergestellt werden. Endgültiges Löschen, Aufbewahrungsregeln und Massenarchivierung sind weiterhin geplant.

Wenn eine Auth-Definition eine Audit-Tabelle angibt, schreiben CRUD-Erstellen, Ändern, Löschen, Archivieren, Wiederherstellen und eigene Aktionen ihre Ereignisse in derselben MariaDB-Transaktion. Passwörter, Tokens, Geheimnisse und Hashes werden aus Änderungsdetails entfernt.

13. Authentifizierung und Berechtigungen

🧪 Zelyra unterstützt Argon2-Login, persistente MariaDB-Sessions, Logout, Routenschutz und datenbankgestützte Berechtigungsprüfungen. Fünf Fehlversuche für dieselbe normalisierte E-Mail-Adresse innerhalb von 15 Minuten lösen eine 60-sekündige HTTP-429-Sperre aus. Ein erfolgreicher Login rotiert das vorherige Session-Token dieses Browsers und entwertet es.

Jedes schreibende Browserformular benötigt sein CSRF-Token sowie einen gleichursprünglichen Origin- oder Referer-Header, der zu Host und dem effektiven Schema der Anfrage passt. Fehlende, fehlerhafte oder fremde Angaben werden abgelehnt. Ein aus einem anderen Browser kopiertes Token reicht somit nicht für eine Website-übergreifende Formularanfrage. Schreibende API-Anfragen mit Browser-Origin-Angaben durchlaufen dieselbe Prüfung; Website-übergreifender API-Zugriff ist nur für einen exakt in der CORS-Richtlinie freigegebenen Origin möglich. API-Anfragen mit Browser-Origin-Angaben oder Browser-Session-Cookie durchlaufen diese Prüfung ebenfalls. Das gilt auch für GET, weil Handler noch nicht statisch auf schreibgeschütztes Verhalten beschränkt sind. Website-übergreifende API-Aufrufe sind nur für einen exakt in der CORS-Richtlinie freigegebenen Origin möglich; mit Session-Cookie muss CORS zusätzlich Credentials erlauben. Das aktuelle CSRF-Token gilt pro Prozess und wird noch nicht einzeln pro Session gespeichert; deshalb sind diese Origin-Prüfungen ein notwendiger Bestandteil des Schutzes.

Der Zelyra-Server spricht derzeit ausschließlich unverschlüsseltes HTTP. Schalte ihm einen vertrauenswürdigen TLS-terminierenden Proxy vor, bevor die Anwendung außerhalb eines lokalen Entwicklungsrechners erreichbar ist. Der Proxy muss den öffentlichen Host erhalten, X-Forwarded-Proto mit dem tatsächlichen externen Schema überschreiben und direkten öffentlichen Zugriff auf den Anwendungsport verhindern. Zelyra verwendet den Header für die Prüfung des effektiven Origins und setzt bei HTTPS das Cookie-Attribut Secure. Vertraue an einer öffentlich erreichbaren Proxy-Grenze niemals ungeprüften, vom Client gelieferten Forwarded-Headern.

Zusätzlich prüft der Server jeden vorhandenen Host-Header gegen ZELYRA_ALLOWED_HOSTS. Der Standard erlaubt nur localhost, 127.0.0.1 und [::1]; das verhindert unter anderem DNS-Rebinding über frei gewählte Hosts. Mehrfach vorhandene sicherheitsrelevante Request-Header wie Host, Origin, Referer, Cookie und Authorization werden abgelehnt, damit keine mehrdeutige Auswertung entsteht. Die Antwort-Policy Referrer-Policy: same-origin ermöglicht gleichursprünglichen API-GETs diesen Nachweis, sendet aber keine Referrer-Informationen an andere Origins. Für eine eigene Domain oder einen LAN-Host muss der tatsächliche Hostname explizit in der kommagetrennten .env-Einstellung ergänzt werden. Es werden keine Schemes, Ports oder Wildcards akzeptiert. Prozessumgebung hat Vorrang vor Projekt-.env und Standardwert. Die Allowlist ersetzt weder TLS noch die Origin-/CSRF-Prüfung.

Einen Wert für die erforderliche Spalte password_hash mit der CLI erzeugen. Der interaktive Befehl schaltet die Passwortanzeige aus und verlangt eine Bestätigung:

zelyra auth hash-password

Für bewusste Automatisierung eine Passwortzeile mit --stdin übergeben. Echte Passwörter nicht als Kommandoargument verwenden und erzeugte Hashes nicht in die Versionsverwaltung übernehmen:

printf '%s\n' 'dieses-passwort-aendern' | zelyra auth hash-password --stdin

auth users {
    table: users
    permissions: user_permissions
    roles: user_roles
    role_permissions: role_permissions
}

page "/admin" {
    requires auth
    permits "machines.manage"

    html {
        <h1>Maschinenverwaltung</h1>
    }
}

Die optionale Tabelle permissions enthält user_id und permission für direkte Vergaben. Rollengruppen werden mit roles und role_permissions aktiviert: Die erste Tabelle enthält user_id und role, die zweite role und permission. Effektive Berechtigungen sind die Vereinigung direkter Vergaben und aller Berechtigungen aus den Rollen des Benutzers. In der integrierten Administrationsansicht übermittelt auch das Formular zum Entziehen von Berechtigungen das korrekte CSRF-Token und entfernt Berechtigungen zuverlässig.

Dieselben Schutzregeln sichern typisierte API-Handler:

api GET "/api/machines/{id}" {
    handler get_machine
    requires auth
    permits "machines.view"
    input { id: MachineId }
    output Machine
    errors { 404 NotFound }
}

Fehler bei geschützten APIs verwenden JSON mit code und message. Ein Handler kann Err("NotFound") zurückgeben, um den passenden Status aus dem deklarierten errors-Block zu wählen; nicht deklarierte Fehler führen zu 500. JSON-Arrays können an typisierte Felder wie Int[] oder MachineId[] gebunden werden. Verschachteltes JSON wird über deklarierte Records modelliert:

struct Address { city: String }
struct CustomerInput { name: String address: Address }

api POST "/customers" {
    handler echo_customer
    input { customer: CustomerInput }
    output CustomerInput
}

Unbekannte Record-Felder und fehlende Pflichtfelder werden abgelehnt. Im Sprachkern unterstützen Arrays Literale, Indexzugriff, len, append, contains, first, last und Verkettung mit +. Record-Literale und geprüfter Feldzugriff stehen für verschachtelte Werte zur Verfügung:

customer = CustomerInput {
    name: "Anna"
    address: Address { city: "Berlin" }
}

print(customer.address.city)

Die Array-Iteration verwendet for ... in; die Schleifenvariable ist unveränderlich und nur im Schleifenkörper sichtbar. break und continue werden unterstützt.

Einen mit Browsern und Node kompatiblen TypeScript-Client aus denselben API-Deklarationen erzeugen:

zelyra doc examples/api_records.zyl --typescript > customer-client.ts

Der erzeugte Client verwendet die standardmäßige fetch-API, enthält deklarierte Records und Tabellen als TypeScript-Typen und behandelt Pfad-/Query-Parameter, JSON-Bodies, Bearer-Tokens, Response-Typen und HTTP-Fehler. Deklarierte API-Fehlernamen sind über ZelyraApiErrorCode verfügbar; ZelyraApiError.fromResponse liest Status, Code und Servermeldung aus und bewahrt den unveränderten Response-Body auf.

API-Fehler können zusätzlich einen geprüften Payload enthalten. Der Payload- Typ wird nach einem Doppelpunkt angegeben und muss dem Fehlertyp im Result des Handlers entsprechen:

struct ValidationProblem {
    field: String
    message: String
}

api POST "/customers/validate" {
    handler validate_customer
    output Result<String, ValidationProblem>
    errors { 422 ValidationError: ValidationProblem }
}

Die Antwort behält error.code und error.message und ergänzt den serialisierten Payload als error.details. OpenAPI enthält das Details-Schema; der erzeugte Client stellt es über ZelyraApiErrorPayloads und das generische Feld ZelyraApiError.details bereit. Bestehende ungetypte API-Fehler bleiben kompatibel.

Browserzugriff ist standardmäßig deaktiviert. Wenn ein separates Frontend eine API aufrufen soll, werden exakte Origins in der Projektkonfiguration freigegeben:

[web]
allowed_origins = ["http://localhost:5173"]
allow_credentials = false

Zelyra beantwortet API-OPTIONS-Preflight-Anfragen automatisch und fügt CORS-Header nur bei deklarierten API-Routen hinzu. Wildcard-Origins werden abgelehnt; CORS umgeht weder Authentifizierung noch Berechtigungen. Aktiviere Credentials nur für benötigte Browser-Session-Cookies; der Client muss dann zusätzlich credentials: "include" verwenden.

Eine Origin muss mit http:// oder https:// beginnen. Pfade, Query-Strings, Fragmente, Wildcards und ein abschließender Slash sind nicht erlaubt. Erlaubte Antworten erhalten Access-Control-Allow-Origin und Vary: Origin; bei aktivierten Zugangsdaten kommt Access-Control-Allow-Credentials: true hinzu. Eine Preflight-Antwort liefert HTTP 204 mit den erlaubten Methoden und angeforderten Headern. Verbotene Origins oder Methoden werden als strukturierte JSON-Fehler beantwortet; bei einem Methodenfehler enthält die Antwort den Allow-Header.

Ein ausgeblendeter Button ist keine Sicherheitsgrenze. Berechtigungen müssen serverseitig an der Aktion geprüft werden. Der Browser ist kreativ, besonders wenn man ihm vertraut.

API-Eingaben und sichere Antwort-Defaults

API-Bodies für Methoden außer GET und DELETE dürfen aktuell application/json oder application/x-www-form-urlencoded verwenden. Nicht unterstützte Medientypen liefern HTTP 415 als strukturierten JSON-Fehler. JSON-Bodies müssen ein Objekt sein; anschließend wird jedes deklarierte Feld in den Zelyra-Typ umgewandelt und geprüft.

Der HTTP-Parser prüft Content-Length, liest vollständige Bodies auch über mehrere Netzwerk-Reads ein und begrenzt Request-Bodies auf 1 MiB. Header sind auf 64 KiB begrenzt. Ein zu großer Body wird vor dem Handler mit HTTP 413 abgelehnt.

Alle HTML-, JSON-, Redirect-, Fehler- und Preflight-Antworten erhalten diese sicheren Standard-Header:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: same-origin

Diese Defaults ersetzen weder TLS noch Authentifizierung, Autorisierung, CSRF-Schutz oder eine geeignete Content-Security-Policy.

Rollenverwaltung und manipulationssichtbares Audit

🧪 Rollen und Rollenberechtigungen können mit den vorhandenen CLI-Befehlen gepflegt werden, wenn die auth-Definition die Tabellen dafür konfiguriert:

auth users {
    table: users
    sessions: auth_sessions
    permissions: user_permissions
    roles: user_roles
    role_permissions: role_permissions
    audit: auth_audit_log
    admin_path: "/admin/access"
    admin_permission: "auth.manage"
    admin_role: admin
}

DATABASE_URL='mariadb://user:passwort@127.0.0.1:3306/app' \
  zelyra auth role grant app.zyl 42 manager
DATABASE_URL='mariadb://user:passwort@127.0.0.1:3306/app' \
  zelyra auth role-permission grant app.zyl manager customers.edit

revoke entfernt die jeweilige Zuordnung wieder. Die Befehle binden Werte als SQL-Parameter und prüfen zunächst das Projektschema. Verwende für echte Passwörter niemals den Platzhalter direkt aus diesem Beispiel.

Mit audit: auth_audit_log lassen sich Authentifizierungs-, Rollen- und CRUD-Ereignisse untersuchen oder exportieren:

DATABASE_URL='mariadb://user:passwort@127.0.0.1:3306/app' \
  zelyra audit inspect app.zyl --limit 100
DATABASE_URL='mariadb://user:passwort@127.0.0.1:3306/app' \
  zelyra audit export app.zyl --format json > audit.json
zelyra audit verify app.zyl

Für eine sichtbare Manipulationserkennung kann die Verkettung aktiviert werden:

auth users {
    table: users
    audit: auth_audit_log
    audit_chain: true
}

Die Audit-Tabelle benötigt dann id, previous_hash und entry_hash, üblicherweise String(64). Zelyra verwendet kleingeschriebene SHA-256- Hexwerte. Der Hash bezieht sich auf die kanonische, mit | getrennte Folge previous_hash|actor_user_id|event|target_user_id|details|created_at. zelyra audit verify prüft Verknüpfungen und Hashes. Das Bereinigen ist für verkettete Protokolle absichtlich deaktiviert, weil das Löschen eines Eintrags die Kette brechen würde. Nicht verkettete alte Einträge können dagegen mit zelyra audit prune ... --before ... --confirm kontrolliert entfernt werden.

Eine optionale Browser-Administrationsseite wird durch admin_path, admin_permission und admin_role aktiviert. Sie kann Benutzer, Passwörter, Aktivierung, Rollen und Rollenberechtigungen verwalten; die Formulare sind CSRF-geschützt. Der Schutz des letzten aktiven Administrators bleibt aktiv.

14. Capabilities

✅ Externe Fähigkeiten werden sichtbar deklariert:

fn load_machines() -> Machine[]
    uses Database
{
    return sql<Machine[]> {
        SELECT id, number, name FROM machines
    }
}

Bekannte Capabilities:

Database Network FileSystem Environment Process Clock Random Console Email

Aufrufende Funktionen müssen benötigte Capabilities weiterführen. Projekte können sie in zelyra.toml freigeben:

[capabilities]
database = true
network = false

Statische Prüfung und Runtime-Durchsetzung an Funktions-, nativen SQL-, Formular-, CRUD- und Authentifizierungs-Datenbankgrenzen sind bei vorhandenen Projektfreigaben implementiert. Eine vollständige Betriebssystem-Sandbox für alle Capabilities ist noch nicht vorhanden.

Zwei sichere Host-APIs sind implementiert:

fn runtime_timestamp() -> Timestamp uses Clock {
    return now()
}

fn configured_mode() -> String? uses Environment {
    return env("ZELYRA_MODE")
}

now() benötigt Clock und liefert Unix-Epoch-Millisekunden. env(name) benötigt Environment und liefert String?; eine fehlende Variable wird zu None. Werte werden nicht automatisch protokolliert oder veröffentlicht. Die Netzwerk-, Datei-, Prozess- und Zufalls-APIs sind implementiert, benötigen aber jeweils eigene Ressourcenfreigaben und bleiben in ihrer ersten Fassung bewusst eingeschränkt.

Die Random-Capability erzeugt sichere Ganzzahlen:

fn dice_roll() -> Int uses Random {
    return random_int(1, 6)
}

Der Bereich ist auf beiden Seiten inklusiv. Ungültige Bereiche führen zu einem Runtime-Fehler; Zufallswerte werden nicht implizit ausgegeben. Prozessausführung ist nur über die folgende, ausdrücklich begrenzte API verfügbar.

Die erste Network-Host-API ist http_get:

fn load_status(url: String) -> String uses Network {
    return http_get(url)
}

Projekte verwenden eine exakte Host-Allowlist und begrenzte Ressourcen:

[network]
allowed_hosts = ["127.0.0.1:8080", "api.example.com"]
timeout_ms = 5000
max_response_bytes = 1048576

Ohne [network] sind in einem Projekt keine Hosts erlaubt. Der Transport unterstützt http:// und https://; die Zertifikatsprüfung über Rustls ist standardmäßig aktiviert. Es werden keine Redirects verfolgt und nur erfolgreiche UTF-8-GET-Response-Bodies innerhalb der konfigurierten Grenzen geliefert. Der Helper http_get bleibt die einfache GET-Komfort-API; für Request-Header, Request-Bodies oder den Response-Status wird http_request verwendet.

Typisierte Anfragen verwenden http_request:

fn create_customer(url: String) -> HttpResponse uses Network {
    return http_request(
        "POST",
        url,
        ["Content-Type: application/json"],
        Some("{\"name\":\"Anna\"}")
    )
}

Die Methode akzeptiert GET, POST, PUT, PATCH, DELETE und HEAD. Header sind Strings im Format Name: value, der Body ist String?. Das typisierte Ergebnis enthält status: Int, headers: String[] und body: String. GET- und HEAD-Anfragen dürfen keinen Body enthalten.

JSON-Werte können in geprüfte Zelyra-Werte umgewandelt werden und umgekehrt. Records und verschachtelte Felder werden gegen das deklarierte Schema geprüft:

struct Customer { name: String tags: String[] nickname: String? }

fn decode_customer(body: String) -> Customer {
    return json_decode<Customer>(body)
}

fn encode_customer(customer: Customer) -> String {
    return json_encode(customer)
}

json_decode<Typ>(text) benötigt genau ein Zieltypargument und unterstützt Records, verschachtelte Records, Arrays, Optionen und Skalarwerte. json_encode serialisiert dieselben Werte. Ungültiges JSON, Typfehler, unbekannte Record-Felder und fehlende Pflichtfelder werden als ausdrückliche Laufzeitfehler gemeldet.

Für einen vollständigen typisierten JSON-Request-/Response-Ablauf gibt es http_json mit getrennten Request- und Response-Typargumenten:

struct CustomerCreate { name: String }
struct Customer { id: Int name: String }

fn create_customer(url: String, payload: CustomerCreate) -> Customer uses Network {
    return http_json<CustomerCreate, Customer>("POST", url, [], Some(payload))
}

Der Request-Record wird automatisch serialisiert und der Response-Body in den Response-Record dekodiert. Wenn kein Content-Type angegeben ist, wird application/json ergänzt. Nicht-2xx-Antworten sind ausdrückliche Laufzeitfehler; der Helper liefert den dekodierten Wert und nicht die Response-Header zurück.

Wenn die Response-Metadaten erhalten bleiben müssen, wird http_result verwendet:

fn submit(url: String, payload: CustomerCreate) -> HttpResult<Customer> uses Network {
    return http_result<CustomerCreate, Customer>("POST", url, [], Some(payload))
}

HttpResult<Response> enthält status: Int, headers: String[], body: String, data: Response? und error: HttpError?. Erfolgreiche 2xx-Antworten setzen data; Nicht-2xx-Antworten setzen error mit Status, Headern, Body und Meldung. Transportfehler und ungültiges Erfolgs-JSON bleiben Laufzeitfehler.

Die Process-Capability stellt eine Befehls-API ohne Shell bereit:

fn render_report(input: String) -> String uses Process {
    return run_process("/usr/bin/printf", ["%s", input])
}

Für Projekte ist eine exakte Befehls-Allowlist erforderlich:

[process]
allowed_commands = ["/usr/bin/printf"]
timeout_ms = 5000
max_output_bytes = 1048576

Ohne [process] darf kein Befehl laufen. Die Umgebung des Kindprozesses wird geleert, stdin geschlossen, Prozesse werden nach dem Timeout beendet und stdout/stderr begrenzt. Shell-Ausführung, Umgebungsweitergabe, Arbeitsverzeichnisse und Pipelines folgen später.

Die FileSystem-Host-APIs sind:

fn read_source(path: String) -> String uses FileSystem {
    return read_text(path)
}

fn write_note(path: String, content: String) uses FileSystem {
    write_text(path, content)
}

fn entries(path: String) -> String[] uses FileSystem {
    return list_dir(path)
}

fn remove_note(path: String) uses FileSystem {
    delete_file(path)
}

Alle vier APIs benötigen FileSystem. Lesen und Verzeichnislisten verwenden read_roots; Schreiben und Löschen verwenden write_roots. Relative Pfade werden ausgehend vom Projektverzeichnis aufgelöst, vorhandene Symlink-Ziele vor dem Zugriff kanonisiert. Ohne filesystem-Abschnitt sind Projektlesezugriffe auf das Projektverzeichnis begrenzt; Schreiben und Löschen sind gesperrt:

[filesystem]
read_roots = ["."]
write_roots = ["data"]

Die konfigurierten Verzeichnisse müssen bereits existieren. Ein neues Schreibziel benötigt ein bereits existierendes Elternverzeichnis.

Strukturierte Nebenläufigkeit

Für einen ersten eingeschränkten Nebenläufigkeitsablauf gibt es parallel und await:

parallel {
    customer = await load_customer()
    orders = await load_orders()
}

Jeder Zweig bindet sein Ergebnis mit await. Die Zweige erhalten eine unveränderliche Momentaufnahme der umgebenden Werte und werden vor der Fortsetzung in Quelltextreihenfolge zusammengeführt. Ein Fehler in einem Zweig lässt den gesamten Block fehlschlagen, nachdem die gestarteten Zweige beendet wurden. await außerhalb eines parallel-Blocks weist der Type Checker ab. Die aktuelle Runtime verwendet einen Worker-Thread pro Zweig; Abbruch und die Verwendung eines Datenbank-Connection-Pools sind noch nicht umgesetzt.

15. Contracts und Verify

🧪 Vor- und Nachbedingungen:

fn reserve(stock: Int, amount: Int) -> Int
    requires {
        amount > 0
        stock >= amount
    }
    ensures {
        result >= 0
        result == stock - amount
    }
{
    return stock - amount
}

requires wird vor dem Funktionskörper, ensures danach geprüft. In ensures bezeichnet result den Rückgabewert.

zelyra verify examples/contracts.zyl

Mögliche Statuswerte:

PROVEN
RUNTIME_CHECK
UNPROVEN
FAILED

Nur PROVEN bedeutet bewiesen. RUNTIME_CHECK trägt keinen falschen Schnurrbart und behauptet nicht, Mathematik zu sein.

Der Verifier fasst außerdem Funktionsaufrufe mit begrenzter Tiefe zusammen. Eine Callee mit mehreren Rückgabepfaden, etwa eine Absolutwertfunktion, liefert ihre Pfadbedingungen an den aufrufenden Contract. requires-Bedingungen der Callee werden nach Argumentsubstitution geprüft; requires des Aufrufers sind Annahmen beim Beweis seiner ensures. Komplexe, rekursive oder nicht auflösbare Fälle bleiben RUNTIME_CHECK.

Lokaler Zustandsfluss wird in diesen Zusammenfassungen berücksichtigt. Sowohl next: Int = value + 1 als auch die Kurzform next = value + 1 mit anschließendem return next werden wie eine direkte Rückgabe analysiert. Einfache lineare Mutable-Zuweisungen wie next = next + 1 werden ebenfalls verfolgt. Statisch begrenzte Schleifen mit linearem Zähler werden entfaltet; break beendet die aktuelle Schleife und continue startet ihren nächsten Durchlauf als eigene symbolische Pfade. Nichtlineare Zuweisungen und unbeschränkte Schleifen ohne bewiesene Invariante bleiben konservativ.

Schleifeninvarianten

Eine while- oder unbedingte loop-Schleife kann eine oder mehrere explizite Invarianten deklarieren:

while current > 0
    invariant { current >= 0 }
{
    current = current - 1
}

Der Verifier prüft die Invariante beim Eintritt und nach unterstützten Körperpfaden. Eine bewiesene Invariante kann eine ansonsten unbeschränkte lineare while-Schleife zusammenfassen; eine unbedingte loop-Schleife kann sie mit einem modellierten break-Austritt verwenden. Die Runtime prüft sie vor und nach jedem Durchlauf. Nicht unterstützte oder nicht beweisbare Invarianten bleiben konservativ und erzeugen kein PROVEN-Ergebnis.

zelyra verify meldet jede deklarierte Invariante separat, nach den ensures-Ergebnissen einer Funktion. Die Indizes der Invarianten beginnen bei null:

PROVEN [V-001]: reduce.ensures[0] (src/reduce.zyl:3:5-3:21)
PROVEN [V-001]: reduce.invariant[0] (src/reduce.zyl:7:21-7:33)
FAILED [V-004]: reduce.invariant[1] (src/reduce.zyl:8:21-8:34)

Jedes Ergebnis enthält einen stabilen Code und einen Quellbereich als (datei.zyl:startzeile:startspalte-endzeile:endspalte). Die Codes sind V-001 (PROVEN), V-002 (RUNTIME_CHECK), V-003 (UNPROVEN) und V-004 (FAILED). Für IDEs und CI kann zelyra verify app.zyl --json verwendet werden; die JSON-Ausgabe enthält dieselben Ergebnisdaten, eine verständliche message, ein optionales counterexample-Objekt und ein strukturiertes location-Objekt. Ein Gegenbeispiel wird nur ausgegeben, wenn eine begrenzte Suche einen kleinen linearen Integerzeugen sicher bestätigt. Die aktuelle Suche umfasst bis zu drei lineare Variablen im Bereich -32..=32, auch bei fehlgeschlagenen Schleifeninvarianten; sonst ist der Wert null. Die Textausgabe zeigt außerdem für jedes Ergebnis eine Erklärung und einen Quellzeilenausschnitt mit Caret-Marker.

FAILED bedeutet, dass die Invariante auf einem möglichen analysierten Pfad falsch ist oder vom Schleifenkörper nicht erhalten bleibt. RUNTIME_CHECK bedeutet, dass eine Laufzeitprüfung erforderlich ist, weil der symbolische Verifier den Beweis nicht vollständig führen kann. Nur PROVEN ist ein mathematischer Beweis.

16. Konfiguration und Geheimnisse

Projektkonfiguration gehört in zelyra.toml, Geheimnisse nicht:

[project]
name = "maschinenverwaltung"
version = "0.9.9"
zelyra = "0.1"

[capabilities]
database = true
network = false

Verbindungen und Passwörter werden über geschützte Umgebungsvariablen bereitgestellt:

export DATABASE_URL='mariadb://user:password@127.0.0.1:3306/zelyra_demo'

Regeln:

Einfacher Einstieg, optionale Feature-Schalter

Für den einfachen Einstieg ist keine zusätzliche Feature-Konfiguration erforderlich. Erweiterte Projektbereiche können in zelyra.toml ausgewählt werden; umgebungsabhängige, nicht geheime Überschreibungen gehören in .env oder die Prozessumgebung:

[features]
web = true
api = true
crud = true
auth = true
audit = true
Schalter .env / Prozessvariable Standard Bedeutung
web ZELYRA_FEATURE_WEB true Seiten, Formulare und Web-Ressourcen
api ZELYRA_FEATURE_API true api-Deklarationen und API-Oberfläche
crud ZELYRA_FEATURE_CRUD true crud-Deklarationen und generierte CRUD-Oberfläche
auth ZELYRA_FEATURE_AUTH true auth-Deklarationen und Authentifizierungsoberfläche
audit ZELYRA_FEATURE_AUDIT true Audit-Konfiguration innerhalb der Authentifizierung

Auswertungsreihenfolge für Konfigurationswerte:

Prozessumgebung → .env → zelyra.toml → sichere Standardwerte

Wenn der Quellcode einen deaktivierten Bereich verwendet, meldet der Compiler E-FEATURE-001. Feature-Schalter können niemals Typprüfung, SQL-Prüfung, Capabilities, Contracts, CSRF-Schutz oder Sicherheitsregeln abschalten.

Die wirksame Konfiguration kann jederzeit geheimnisfrei geprüft werden:

zelyra config main.zyl
zelyra config main.zyl --format=json

.env-Werte des generierten Projekts

Variable Standard im generierten Projekt Verwendung Geheim
ZELYRA_WEB_PORT 3000 Port des internen Webservers im Container nein
ZELYRA_HOST_PORT 3000 (oder autom. freier Port) lokal veröffentlichter Webport nein
ZELYRA_DB_HOST_PORT 3306 (oder autom. freier Port) lokal veröffentlichter MariaDB-Port nein
DATABASE_URL projektabhängig MariaDB-Verbindungs-URI (mariadb://user:pass@host:port/db) ja
MARIADB_DATABASE zelyra_app Compose: Datenbankname nein
MARIADB_USER zelyra Compose: Anwendungsbenutzer nein
MARIADB_PASSWORD zufällig erzeugt Compose: Passwort des Anwendungsbenutzers ja
MARIADB_ROOT_PASSWORD zufällig erzeugt Compose: MariaDB-Root-Passwort ja
ZELYRA_AUTH_TOKEN keiner optionaler lokaler Bearer-Token für geschützte Anfragen ja
ZELYRA_AUTH_PERMISSIONS leere Liste kommagetrennte lokale Berechtigungs-Allowlist nein

Test- und Entwicklungsvariablen

Die Testvariablen mit ZELYRA_INSTALL_ROOT, ZELYRA_BIN, *_E2E_* und GENERATED_* dienen internen CI- und lokalen Integrationstests (z. B. tests/generated-project-docker-e2e.sh, tests/sqlite-e2e.sh). Sie sind keine Anwendungskonfiguration und dürfen nie Produktionszugänge enthalten.

Umgebungszugriff innerhalb der Sprache

Über die Built-in-Funktion env(name) kann Zelyra-Code Werte aus der Umgebung lesen, sofern uses Environment und [capabilities] environment = true deklariert sind:

fn configured_mode() -> String? uses Environment {
    return env("ZELYRA_MODE")
}

DATABASE_URL und sensible Schlüssel dürfen niemals per env(...) in ungesichertem Code ausgelesen werden.

17. Diagnosen und Fehlersuche

Zelyra möchte Fehler so erklären, dass man nicht erst eine archäologische Ausgrabung im Stacktrace beginnen muss.

Verbindung unabhängig testen

Teste zuerst MariaDB ohne Zelyra. Das Passwort wird interaktiv abgefragt und landet nicht in der Shell-History:

mariadb \
    --host=127.0.0.1 \
    --port=3307 \
    --user=zelyra \
    --password \
    adressverwaltung

Danach ist zelyra doctor src/main.zyl --json (optional mit --env-file .env und --port 18080) der vorhandene Zelyra-Test. Es gibt aktuell keinen zelyra db check-Befehl. doctor prüft Quellcode, Schema, DB-Verbindung, Docker Compose und Host-Ports. Ohne DATABASE_URL meldet er nur eine Warnung, bei einer gesetzten, aber nicht erreichbaren Verbindung einen Fehler. Ein laufender DB-Container allein beweist noch nicht, dass Host, Port, Benutzer und Datenbank zusammenpassen.

Diagnosebefehle ohne Geheimnisse

pwd
ls -la
docker compose ps
docker compose logs mariadb
ss -ltn
mariadb --version

Unter Windows in PowerShell sind Get-Location, Get-ChildItem, docker compose ps und mariadb --version die entsprechenden ersten Schritte. Gib niemals DATABASE_URL oder ein Passwort in eine Diagnoseausgabe aus.

Typische Fehler

Fehlermeldung Wahrscheinliche Ursache Lösung
Permission denied fehlende Dateirechte, falscher Besitzer oder kein Zugriff auf den Client ls -la, chmod 600 .env und Installationspfad prüfen
Access denied for user Passwort stimmt nicht oder Benutzer ist für einen anderen Host angelegt SHOW GRANTS FOR 'zelyra'@'127.0.0.1'; prüfen; Passwort rotieren
Connection refused auf Host/Port lauscht kein Dienst docker compose ps, ss -ltn und den veröffentlichten Port prüfen
Can't connect to server falscher Host, falscher Port oder Container noch nicht bereit docker compose logs mariadb; vom Host 127.0.0.1:3307, im Compose-Netz mariadb:3306 verwenden
Unknown database Datenbankname in URL und MariaDB unterscheiden sich SHOW DATABASES; ausführen und DATABASE_URL korrigieren
falscher Port außen 3307 mit innen 3306 verwechselt Host nutzt 3307, ein Compose-Service nutzt 3306
MariaDB-Container nicht gestartet Compose-Fehler, belegter Port oder ungesundes Volume docker compose ps und docker compose logs mariadb prüfen
Benutzer nur für anderen Host freigegeben 'zelyra'@'localhost' ist nicht immer 'zelyra'@'127.0.0.1' Benutzer exakt für den verwendeten Host anlegen und Grants kontrollieren
fehlende Umgebungsvariable DATABASE_URL wurde nicht exportiert .env laden oder Variable für den Prozess setzen; Zelyra lädt sie nicht selbst
.env wird nicht gefunden falsches Arbeitsverzeichnis oder Annahme eines automatischen Loaders pwd, ls -la; im Projektstamm arbeiten und Variable explizit exportieren
ungültiger Zahlenwert beim Port Portteil der URI ist kein gültiger MariaDB-Port Ziffern verwenden, zum Beispiel 3307; die URL wird ansonsten abgelehnt
falscher Zeichensatz Datenbank mit anderem Charset/Kollation angelegt Datenbankdefinition prüfen; db setup nutzt utf8mb4/utf8mb4_unicode_ci
TLS-Fehler TLS-Parameter wurden an die URL angehängt, werden aber nicht unterstützt aktuelle CLI-URL ohne TLS-Query-Option nutzen; TLS-Konfiguration ist geplant
Testdatenbank wird aus Sicherheitsgründen abgelehnt Schutzmechanismus wird erwartet, ist aber nicht implementiert Zelyra verhindert Produktionszugriff in Tests nicht automatisch; Variablen manuell prüfen
PostgreSQL-SQL gegen MariaDB falsches Backend oder nicht passende DDL Backend in .zyl prüfen und zelyra db create-Ausgabe vor Anwendung lesen

Wenn mariadb gar nicht gestartet werden kann, nennt Zelyra den Startfehler des externen Programms. Der CLI-Prozess enthält keinen eigenen MariaDB-Treiber.

Quellcode prüfen:

zelyra check app.zyl

Typische Fehlerklassen:

Beim Entwickeln kannst du _ als Platzhalter für einen unfertigen Ausdruck einsetzen (Typed Hole). zelyra check lehnt unfertigen Code für den Bau zwar ab, liefert aber kontextbezogene Diagnosen: erwarteter Typ, sichtbare Variablen und Funktionen, aktive Capabilities, Contract-Pflichten und Quelltextposition.

Wenn DATABASE_URL fehlt, funktionieren reine Sprachprüfungen weiterhin. Datenbankoperationen melden den fehlenden Zugriff kontrolliert. Das run- Kommando verwendet ohne Variable die reine Runtime; serve startet zwar die Routen, datenbankabhängige Seiten antworten aber mit einem kontrollierten Fehler.

18. Testen und Mitentwickeln

Vor jedem Commit:

cargo fmt --all
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

Ein Sprachfeature ist erst fertig, wenn es besitzt:

Tests, die nur deshalb grün sind, weil sie nie liefen, sind Dekoration.

19. Was als Nächstes kommt

Die wichtigsten geplanten Bereiche:

Zelyra soll den Standardfall kurz halten und beim Sonderfall nicht plötzlich die Tür abschließen:

Automatisch, wenn möglich. Anpassbar, wenn nötig. Überall geprüft.

Und jetzt: eine Tabelle bauen, SQL lesen, Backup prüfen. In dieser Reihenfolge.

20. Zelyra im Vergleich zu Rust

Die wichtigste Aussage zuerst

Zelyra wird mit Rust entwickelt. Der Zelyra-Compiler, die Sprachmodule und Teile der Laufzeit liegen als Rust-Crates im Compiler-Repository. Das bedeutet nicht, dass Zelyra Rust verändert oder dass Zelyra-Anwendungsprogramme Rust- Programme sind.

Zelyra ist nicht verändertes Rust. Zelyra ist eine eigenständige Sprache, deren Compiler und Laufzeit in Rust entwickelt werden.

Der Rust-Compiler wird für Zelyra nicht geforkt und nicht um Zelyra-Schlüssel- wörter erweitert. Zelyra ist auch keine Rust-Bibliothek und kein Präprozessor, der gewöhnlichen Rust-Code in etwas anderes umschreibt. Eine .zyl-Datei wird vom eigenen Zelyra-Lexer und -Parser gelesen, in eigene AST-/HIR-Strukturen überführt, typgeprüft und anschließend von der Zelyra-Runtime verarbeitet.

Die Ähnlichkeit bei fn, geschweiften Klammern, if, match oder statischer Typisierung ist eine Designentscheidung, aber kein Abstammungsnachweis. Entschei- dend sind Grammatik, Semantik und Programmiermodell. Zelyra ist derzeit noch ein experimenteller Prototyp; die Eigenständigkeit wächst mit der Umsetzung des eigenen Typsystems, der SQL-Prüfung, der Runtime und der Zelyra-spezifischen Konstrukte.

Die Aussagen in diesem Kapitel wurden gegen den aktuellen Quellcode geprüft: Lexer und TokenKind definieren die Zelyra-Tokens, der Parser erzeugt eigene AST-Strukturen, und die nachfolgenden Module übernehmen Auflösung, Typprüfung, Contract-Prüfung, SQL-Analyse, Webverarbeitung und Runtime. Die CLI- und Datenbankmodule wurden ebenfalls berücksichtigt. Wo ein Merkmal nur als Token, AST-Knoten oder Zielbild vorhanden ist, wird es nicht als vollständig ausführbare Spracheigenschaft ausgegeben.

Allgemeiner Vergleich

Bereich Rust Zelyra Wesentlicher Unterschied Zelyra-Status
Sprachkategorie universelle System- und Anwendungssprache eigenständige deklarative Sprache für Business- und Webanwendungen andere Grammatik und Semantik 🧪
Haupteinsatzgebiet Systeme, Services, CLI, Embedded, WebAssembly datenbankgestützte Business- und Webanwendungen Zelyra bündelt Fachanwendungsebenen 🧪
Compiler rustc, Cargo-Ökosystem eigenes Rust-Programm im Zelyra-Repository Rust kompiliert den Compiler; rustc kompiliert nicht .zyl ✅
Laufzeit Rust-Code läuft nativ oder über gewählte Runtime eigene Zelyra-Runtime, in Rust implementiert Zelyra führt eigene Werte und Regeln aus 🧪
Speicherverwaltung Ownership, Borrowing, Lifetimes für Zelyra-Code weitgehend automatisch verborgen kein Rust-Borrow-Checker im .zyl-Programm 🧪
Ownership zentrale Rust-Semantik kein entsprechendes .zyl-Konstrukt Speicherregeln sind nicht dieselben 🗺️
Borrowing Referenzen und Borrow-Checker kein entsprechendes .zyl-Konstrukt keine Rust-Referenzsyntax 🗺️
Lifetimes explizite oder inferierte Lebensdauern keine Lifetime-Syntax Zelyra legt diese Ebene derzeit nicht offen 🗺️
statische Typisierung sehr ausgereift, generisch und trait-basiert eigener statischer Typechecker mit Int, String, Option, Records usw. Zelyra-Typen sind nicht Rust-Typen ✅
Nullfähigkeit Option<T> T?, etwa Email? Zelyra kann daraus Schema-/Formregeln ableiten ✅
Fehlerbehandlung Result<T, E>, Option<T>, ?-Operator Result<T, E>, Some/None, Laufzeitdiagnosen kein Rust-?-Operator als Zelyra-Syntax ✅
Datenbankintegration externe Crates wie SQLx, Diesel oder SeaORM vorgesehener Bestandteil von Sprache, CLI und Runtime anderes Integrationsmodell; aktuell externer Client 🧪
SQL Bibliotheken, Makros oder Strings natives sql<T> { ... } mit Schema-/Parameterprüfung Zelyra kennt SQL als AST-Ausdruck ✅
MariaDB-Schema nicht Aufgabe der Rust-Sprache Tabellen werden in Zelyra beschrieben Generator erzeugt sichtbares SQL 🧪
Formulare Framework, Templates und Validierung selbst verbinden form-Konstrukt und Tabellenregeln Standardpfad ist Teil des Sprachmodells 🧪
CRUD muss programmiert oder über Frameworks erzeugt werden deklaratives crud Name -> table mit gemeinsamem View-Feldprofil aktuelle Runtime stellt CRUD-Routen bereit 🧪
Views externe Bibliotheken oder Frameworks page/html, benannte view-Layouts, typisierte component-Bausteine und benannte Slots mit Fallbacks sind vorhanden kein Rust-Äquivalent; freie Styling-Komponenten fehlen noch 🧪
Quellformatierung cargo fmt, rustfmt zelyra fmt <file.zyl> [--check] deterministischer Zelyra-Formatter, schützt SQL und HTML ✅
Refactoring/Wirkungsanalyse rust-analyzer, Compiler-APIs zelyra impact, zelyra edit versionierte, atomare JSON-Maschinenschnittstellen 🧪
Authentifizierung externe Web-/Auth-Crates Auth-Definition, Sessions und Berechtigungsprüfungen im Webmodul Zelyra bündelt den Standardfall 🧪
Berechtigungen selbst entworfene Typen und Middleware requires auth, permits und CRUD-Aktionsrechte deklarative Regeln werden serverseitig geprüft 🧪
Contracts manuell oder über Bibliotheken native requires {} und ensures {} plus verify Contract-Syntax gehört zu Zelyra ✅
Capabilities APIs und Bibliotheken regeln Effekte uses Database, uses Network usw. sichtbare Effektdeklaration ist Sprachbestandteil ✅
E-Mails externe SMTP-/Mail-Crates mail_queue, mail_deliver, uses Email MariaDB-Outbox, TLS, Hostfreigabe und ausdrücklich gestarteter Worker 🧪
Jobs externe Job-/Queue-Systeme kein Hintergrundjob-Konstrukt keine stabile Job-Syntax ❌
Audit externe Logs oder Audit-Crates Audit-Tabelle, CLI-Auswertung und optionale Hash-Kette an Auth/CRUD gebunden und noch experimentell 🧪
Deployment Cargo, Container, CI und Infrastruktur frei wählbar generierte Docker-/Compose-Vorlage vorhanden Vorlage ist Entwicklungsstart, keine Produktionsplattform 🧪
Produktionsreife Rust ist breit produktiv eingesetzt Zelyra ist experimentell Reife und Ökosystem sind nicht vergleichbar 🧪
Ökosystem sehr groß: Crates, Tools, Frameworks kleines eigenes Repository und wenige Integrationen Zelyra kann Rust-Crates nicht direkt importieren 🧪

Rust ist also das technische Fundament, nicht die Anwendungssprache hinter Zelyra. Eine Rust-Struktur Customer und eine Zelyra-Tabelle customers können ähnliche Daten beschreiben, erzeugen aber nicht dasselbe Verhalten.

Ausführlicher Syntaxvergleich

Die Statusangabe ✅ bedeutet in diesem Kapitel: im aktuellen Quellcode vorhanden und mit der installierten Rust-Toolchain beziehungsweise dem Zelyra- CLI geprüft. 🧪, 🗺️ und ❌ kennzeichnen weiterhin eingeschränkte, geplante oder derzeit nicht verfügbare Sprachmerkmale.

Sprachmerkmal Zelyra-Syntax Rust-Syntax Semantischer Unterschied Zelyra-Status
Dateiendung app.zyl main.rs eigener Lexer und eigener Dateityp ✅
Programmeinstieg fn main() { ... } fn main() { ... } gleiche Schreibweise, andere Sprache ✅
Funktionsdefinition fn add(a: Int) -> Int { ... } fn add(a: i64) -> i64 { ... } Zelyra-Typen sind eigene AST-Typen ✅
Parameter name: String name: String ähnliche Position, andere Typsemantik ✅
Rückgabetyp -> Int -> i64 Zelyra abstrahiert den Geschäftstyp ✅
Rückgabewert return value value oder return value; letzter Rust-Ausdruck ist Rückgabewert ✅
unveränderliche Variable value = 1 let value = 1; Zelyra bindet ohne mutable unveränderlich ✅
veränderliche Variable mutable value = 1 let mut value = 1; Veränderbarkeit wird anders markiert ✅
Ganzzahl Int oder UInt i32, i64, u32, u64 Rust verlangt konkrete Breite; Zelyra abstrahiert derzeit ✅
Dezimalzahl Float oder Decimal f64 oder f32 Größe und genaue Überlaufregeln von Zelyra sind noch nicht vollständig spezifiziert 🧪
Boolean true, false, Bool true, false, bool eigenes Zelyra-Basistypmodell ✅
Zeichenkette String und Zeichenliterale String, &str, Zeichenliterale Rust unterscheidet Besitz und Borrowing ✅
optionale Werte Email? oder Option<String> Option<String> ? ist Zelyras Kurzform für Option ✅
fehlender Wert None None gleiche Bezeichnung in verschiedenem Enum-Modell ✅
Listen/Arrays Int[], [1, 2, 3] Vec<i64>, vec![1, 2, 3] Zelyra bietet keine Rust-Makrosyntax ✅
benannte Datentypen type CustomerId = Id, struct Customer { ... } type CustomerId = u64, struct Customer { ... } Zelyra-Records und Rust-Structs sind nicht austauschbar ✅
Bedingungen if ok { ... } if ok { ... } Blocksemantik und Ausdrucksregeln unterscheiden sich ✅
else else { ... } else { ... } ähnliche Kontrollflussform ✅
match match value { Some(x) => ... None => ... } match value { Some(x) => ..., None => ... } Zelyra verlangt ebenfalls vollständige Fälle ✅
Schleifen for item in items, while, loop for item in items, while, loop Zelyra unterstützt keine Rust-Iteratortraits ✅
Funktionsaufrufe add(1, 2) add(1, 2) gleiche Oberfläche, andere Auflösung ✅
Ausgabe print(value) println!("{}", value); Rust verwendet ein Makro mit ! ✅
Kommentare # Kommentar, alleinstehendes ## als Blockgrenze // Kommentar, /* ... */ # ist Standard; // bleibt kompatibel; ##-Blöcke sind nicht verschachtelt ✅
Zeilenumbrüche meist Trennzeichen; nach Operatoren fortsetzbar meist Whitespace Parserregeln sind eigenständig ✅
Semikolons werden als Statementtrenner akzeptiert, aber nicht benötigt häufig Statementtrenner Zelyra ist nicht semikolonpflichtig ✅
Blockstruktur { ... } { ... } Klammern bestimmen in beiden die Blöcke ✅
Einrückung Lesbarkeit, keine Blocksemantik Lesbarkeit, keine Blocksemantik Leerzeichen/Tabs werden nicht zu Python-Blöcken ✅
Fehlerbehandlung Result<T, E>, Some/None Result<T, E>, ?, panic! Zelyra hat keinen Rust-Operator ? ✅
Stringinterpolation HTML kann {name} in html-Bodies verwenden format!("{name}") oder println!("{}", name) keine allgemeine Zelyra-Stringinterpolation dokumentieren 🧪
Module Noch nicht festgelegt mod name {}, Dateien und Module keine mod-Syntax im Zelyra-Parser ❌
Imports Noch nicht festgelegt use crate::module::Item; keine Importsyntax ❌
Generics Option<T>, Result<T, E> und begrenzte Built-in-Typargumente allgemeine Generics und Traits keine benutzerdefinierten Zelyra-Generics 🧪
asynchrone Funktionen async fn nicht vorhanden; await/parallel nur eingeschränkt async fn, .await, Futures kein stabiles Zelyra-Async-Modell 🧪
Tabellen table customers { ... } kein Sprachkonstrukt Zelyra verbindet Tabelle und Schema ✅
Datenbanktypen Id, String(100), Email, Bool Rust-Typen und externe Mapping-Crates Zelyra erzeugt SQL-Typen aus der Tabelle ✅
Beziehungen department: Department required Feld plus eigene Query-/Mappinglogik Zelyra leitet Fremdschlüssel ab ✅
SQL-Abfragen sql<Customer[]> { SELECT ... } String/Makro einer DB-Crate Zelyra prüft Schema, Parameter und Ergebnis ✅
Formulare form CustomerCreate -> customers { ... } kein natives Formular Webframework und Validierung nötig ✅
CRUD crud Customer -> customers kein natives CRUD Zelyra-Runtime stellt Standardrouten bereit 🧪
Views page, view SiteShell und component Badge kein natives View-Konstrukt benannte Views/Komponenten sind vorhanden; input/render/?? bleiben Zielsyntax 🧪
Vorbedingungen requires { amount > 0 } kein eingebautes Äquivalent Contract ist Teil der Zelyra-Funktion ✅
Nachbedingungen ensures { result >= 0 } kein eingebautes Äquivalent Verifier und Runtime kennen Zelyra-Contracts ✅
Zugriff auf alte Werte Noch nicht festgelegt; old(...) nicht geparst ebenfalls kein allgemeiner eingebauter Contractstandard keine old-Syntax vortäuschen ❌
Capabilities uses Database kein identisches Sprachkonstrukt Effekte werden in Zelyra sichtbar deklariert ✅
E-Mails mail_queue und mail_deliver externe Crate/API Email-Capability; Einreihen in transaction mit Database(write) 🧪
Hintergrundjobs Noch nicht festgelegt externe Queue-/Runtime-Crate keine Job-Syntax ❌
Audit auth users { audit: auth_audit_log } externe Logging-/Audit-Crate Zelyra bindet Audit an Auth- und CRUD-Ereignisse 🧪
API-Definitionen api GET "/customers" { ... } Router, Handler und Typen separat Zelyra bündelt Vertrag und Route ✅

Funktionen: derselbe Gedanke, andere Sprache

Beide folgenden Beispiele sind in ihrer jeweiligen Sprache typische kleine Funktionen. Das Zelyra-Beispiel entspricht der vom Parser verarbeiteten Funktionssyntax und wurde mit dem aktuellen CLI geprüft.

fn add(a: Int, b: Int) -> Int {
    return a + b
}

fn add(a: i64, b: i64) -> i64 {
    a + b
}

Rust verwendet konkrete Ganzzahltypen wie i32, i64, u32 oder u64. Zelyra bietet für typische Businesslogik den verständlichen Typ Int; die verbindliche Größe, Überlaufbehandlung und jede Datenbankabbildung müssen noch vollständig spezifiziert werden.

Fibonacci

fn fibonacci(n: Int) -> Int {
    if n <= 1 {
        return n
    }

    return fibonacci(n - 1) + fibonacci(n - 2)
}

fn main() {
    print(fibonacci(10))
}

fn fibonacci(n: u64) -> u64 {
    if n <= 1 {
        return n;
    }

    fibonacci(n - 1) + fibonacci(n - 2)
}

fn main() {
    println!("{}", fibonacci(10));
}

✅ Die Zelyra-Fassung nutzt Int, print und explizites return; Rust nutzt u64, das println!-Makro und den letzten Ausdruck als Rückgabewert. Rust- Makros tragen das !. In Zelyra sind Semikolons nicht erforderlich. Klammern bestimmen in beiden Beispielen die Blockstruktur, Einrückung dient nur der Lesbarkeit. Ein Zeilenumbruch nach + setzt den Ausdruck fort; der Parser überspringt an dieser Stelle Zeilenumbrüche. Rekursion funktioniert in Zelyra nur, weil Funktionsauflösung und Runtime sie tatsächlich unterstützen. Der Code wurde in diesem Arbeitslauf nicht ausgeführt.

Optionale Werte

email: Email?

email: Option<String>

Email? ist fachlich kürzer und drückt neben der Optionalität den E-Mail- Datentyp aus. Rust verwendet den allgemeinen generischen Typ Option<T>. Zelyra kann Email? in der Tabellen-, Formular- und SQL-Prüfung berücksichtigen; eine allgemeine automatische View- oder Validierungsableitung ist jedoch nicht für jede Oberfläche vorhanden.

Tabellen

table customers {
    id: Id primary auto
    name: String(100) required
    email: Email?
    active: Bool default true
}

struct Customer {
    id: u64,
    name: String,
    email: Option<String>,
    active: bool,
}

Die Rust-Struktur erzeugt keine Tabelle, keine SQL-Spalten, keine Validierung, kein Formular und keine CRUD-Oberfläche. Dafür braucht Rust zusätzliche Crates, Makros, Queries, Handler und Templates. Die Zelyra-Tabelle wird dagegen in die Schemaableitung und – wo die Webfunktion vorhanden ist – in Formulare und CRUD einbezogen.

CRUD

crud Customer -> customers

Rust besitzt dafür kein natives Äquivalent. Typischerweise kommen in Rust ein Webframework, Routing, eine Datenbank-Crate, ein Datenmodell, Abfragen, Request-Typen, Validierung, Handler, Templates oder ein Frontend, Fehlerbehandlung und Berechtigungsprüfung zusammen. Zelyra parst diese deklarative Definition und die aktuelle Runtime stellt daraus CRUD-Routen, Formulare, Suche, Filter und CSRF-geschützte Aktionen bereit. Das ist experimentell; es ist kein statischer Frontend-Generator.

SQL

Die Zielsyntax aus dem Auftrag enthielt with { ... }. Das ist im aktuellen Parser nicht vorhanden. Parameter kommen derzeit als Funktionsparameter in die SQL-Prüfung:

struct Customer { id: Int name: String email: Email? active: Bool }

fn active_customers(active: Bool) -> Customer[]
    uses Database
{
    return sql<Customer[]> {
        SELECT id, name, email, active
        FROM customers
        WHERE active = :active
        ORDER BY name
    }
}

let customers = sqlx::query_as!(
    Customer,
    r#"
        SELECT id, name, email, active
        FROM customers
        WHERE active = ?
        ORDER BY name
    "#,
    true
)
.fetch_all(&pool)
.await?;

Rust hat SQL nicht als Spracheigenschaft; SQLx oder andere Crates können zusätzliche Compile-Time-Prüfungen anbieten. Zelyras aktueller SQL-Checker prüft – wenn Schema und Typen bekannt sind – Tabellen, Spalten, Aliase, Parameter, Nullfähigkeit, Ergebniszuordnung und Database-Capability. Das macht Zelyra nicht automatisch besser als SQLx. Der aktuelle MariaDB-Generator und seine fehlenden Tabellenoptionen sind in Abschnitt 7 offen dokumentiert.

Views: aktuelle Syntax statt Zielbild

Die gezeigte Zielsyntax mit view, input, render, Komponenten und ?? ist heute nicht Parser-Syntax. Der aktuelle Webkern verwendet stattdessen:

page "/customers/{name}" {
    html {
        <h1>Kunde {name}</h1>
    }
}

Rust besitzt keine eingebaute HTML- oder Komponenten-Syntax; dort kommen Templates und Webframeworks hinzu. Zelyras page/html-Form sowie benannte Views und typisierte Komponenten sind vorhanden. Mehrere Slots, verschachtelte Komponenten und die Zielsyntax mit input/render sind noch nicht stabil; ?? ist keine implementierte Zelyra-Operation.

Verträge

Die Zielsyntax require amount > 0 und old(...) ist nicht der aktuelle Stand. Der Parser akzeptiert requires {} und ensures {}:

fn reserve(stock: Int, amount: Int) -> Int
    requires {
        amount > 0
        stock >= amount
    }
    ensures {
        result >= 0
        result == stock - amount
    }
{
    return stock - amount
}

Rust besitzt hierfür kein direkt eingebautes Äquivalent. requires beschreibt Vorbedingungen, ensures Nachbedingungen. Runtime-Prüfung und formale Verifikation sind verschieden: zelyra verify kann PROVEN, RUNTIME_CHECK, UNPROVEN oder FAILED melden. Ein Zugriff auf den alten Wert über old(...) ist nicht implementiert.

Capabilities

fn load_customers() -> Customer[] uses Database {
    return sql<Customer[]> {
        SELECT id, name, email, active FROM customers
    }
}

uses macht erlaubte Seiteneffekte in der Signatur sichtbar. Database, Network, FileSystem, Environment, Process, Clock, Random und Console sind im aktuellen Runtime-Code bekannte Capabilities. Rust besitzt kein identisches eingebautes Capability-System; dort werden Zugriffe typischerweise über Typen, Werte und Bibliotheks-APIs organisiert. Email ist die Capability für Anwendungs-Mail. mail_queue benötigt zusätzlich Database(write) und eine Transaktion; die SMTP-Zustellung prüft den erlaubten Host.

Was Rust-Kenner in Zelyra nicht suchen sollten

Zelyra soll für typische Businessanwendungen nicht verlangen, im gewöhnlichen Anwendungscode explizite Lifetimes zu schreiben, Borrowing für einfache Formulare zu debuggen, zwischen vielen Ganzzahlbreiten zu wählen oder ein Webframework aus zahlreichen Crates zusammenzustellen. Das ist eine Abstraktion, keine Behauptung, dass Speicher- und Laufzeitfragen verschwinden.

Von Rust inspiriert sind statische Typisierung, verständliche Diagnosen, sichere Standardeinstellungen, explizite Veränderbarkeit, Pattern Matching, Records/Enums, klare Grenzen, reproduzierbares Tooling und formale Prüfungen.

Was Zelyra eigenständig macht

Zelyra-Merkmal Nutzen Status
Eine fachliche Definition weniger widersprüchliche Mehrfachdefinitionen 🧪
natives geprüftes SQL Datenbankfehler möglichst vor Ausführung erkennen ✅
deklaratives CRUD Standardverwaltungen mit wenig Code 🧪
page/html-Webkern einfache typisierte Pfadwerte und HTML-Antworten 🧪
sichtbares MariaDB-SQL nachvollziehbare Schemaänderungen 🧪
requires und ensures Geschäftsregeln ausdrücklich festlegen ✅
Capabilities erlaubte Seiteneffekte sichtbar machen ✅
integriertes Audit Änderungen nachvollziehen 🧪

Ehrliches Fazit

Zelyra sieht an einigen Stellen ähnlich aus wie Rust, weil beide moderne, statisch typisierte Sprachen mit geschweiften Klammern und klaren Funktionssignaturen sind. Zelyra verfolgt jedoch ein anderes Programmiermodell: Datenbank, SQL, Formulare, CRUD, Views und Geschäftsregeln sollen Bestandteile eines gemeinsamen Sprachsystems sein. Rust ist das technische Fundament des Compilers – nicht die Sprache, die Zelyra-Anwendungsentwickler schreiben.

Status: Zelyra ist derzeit ein experimenteller Sprachprototyp. Einige gezeigte Sprachmerkmale beschreiben das verbindliche Zielbild und sind noch nicht vollständig implementiert. Der Status an jedem Beispiel zeigt, was heute im Code tatsächlich vorhanden und geprüft ist.

Weiterführend: Einführung, Sprachgrundlagen, MariaDB, SQL, Formulare, Views/Webseiten, CRUD, Contracts, Capabilities, Implementierungsstatus und Roadmap. Der laufende Repository-Stand steht zusätzlich auf der Statusseite.

21. Positionierung und aktueller Entwicklungsstand

Die aktuelle Positionierung in docs/positioning.de.md beschreibt Zelyra als eigenständige Sprache für datenbankgestützte Businessanwendungen. Sie ersetzt nicht die technische Prüfung im Compiler; sie erklärt, wofür die Bausteine zusammen gedacht sind.

Was Zelyra unterscheidet

  1. Eine Quelle der Wahrheit: Schema, Typen, SQL, Formulare, CRUD, Views und APIs sollen aus miteinander prüfbaren Definitionen entstehen.
  2. SQL bleibt First-Class: SQL wird nicht hinter einer ORM-Abstraktion versteckt, sondern als Bestandteil des Programms mit Tabellen, Parametern und Ergebnisformen geprüft.
  3. Businessfunktionen sind Sprachbausteine: Tabellen, Formulare, CRUD, Seiten, Authentifizierung, Berechtigungen und Contracts gehören zum selben Modell.
  4. Sichere Defaults sind sichtbar: HTML-Escaping, parametrisierte SQL- Werte, CSRF-Schutz, Null-Sicherheit und serverseitige Berechtigungen sind keine bloßen Empfehlungen.
  5. Beweise werden ehrlich bezeichnet: PROVEN, RUNTIME_CHECK, UNPROVEN und FAILED unterscheiden echte statische Beweise von Laufzeitprüfungen und offenen Fällen.
  6. Kurzer Einstieg, vollständige Sprache: Der deklarative Standardfall ist kurz; eigene Funktionen und native SQL bleiben für komplexe Fachlogik verfügbar.
  7. Wenig Infrastruktur für den Start: Der eingebaute Server und die CLI sollen den Lern- und Entwicklungsweg ohne Apache, PHP oder ein verpflichtendes Framework-Bündel ermöglichen.

Der aktuelle Stand ist trotzdem ein experimenteller Prototyp. Die Roadmap und die einzelnen Statuszeichen sind deshalb wichtiger als eine allgemeine Produktbehauptung.

22. Unterstützung und technische Nachweise

Wähle den Backendpfad anhand der Datenbankmatrix. MariaDB 11.4.13 (sowie 10.11.19, 11.8.9 und 12.3.3), MySQL Server 8.4.11 und PostgreSQL 16.15 bilden die verifizierte Multi-Backend-Servermatrix. Relationales CRUD mit echten Fremdschlüsseln (fk_...), Preflight-Waisenabweisung (error[E-DB-005]) unter Datenerhalt, relationalen Joins und restriktivem Löschschutz (RESTRICT-Delete-Policy) ist für alle drei Engines dokumentiert und getestet. Auf MySQL sind Schreibsperren über innodb_lock_wait_timeout dynamisch an Transaktions-Deadlines gebunden. Native Entscheidungstransaktionen (with_decision_transaction) sichern Rollback, Unwind und Deadlines auf einer geliehenen Verbindung ab. SQLite ergänzt lokale Schema- und grundlegende CRUD-Abläufe.

Diese Nachweise gelten für die genannten Abläufe, nicht für beliebige Datenbankfunktionen. Erweiterte Authentifizierungsmerkmale, Mail-Outbox und Benachrichtigungsbeispiele verwenden vorrangig MariaDB und MySQL.

Installation, Upgrade, Rollback, Migration und Wiederherstellung müssen zur eingesetzten Plattform und Serverversion passen. Prüfsummen, SBOMs und Attestierungen helfen, das Release-Artefakt zuzuordnen. Sie bestätigen nicht die fachliche Korrektheit einer Anwendung. Die Betriebs- und Prüfziele verlangen reproduzierbare Proben; ein Ziel allein ist kein bestandener Nachweis.

Für ein Lernprojekt empfiehlt sich: zuerst check und run, dann Schema-Vorschau und Plan, danach Seiten/Formulare/CRUD und schließlich Authentifizierung, Mail und Integrationen.

23. KI-native Entwicklung

Die aktuellen Architektur- und Spezifikationsdokumente ergänzen ein wichtiges Prinzip:

Die KI schreibt. Zelyra prüft.

Zelyra soll für Menschen und KI-Systeme gleichermaßen nutzbar sein, bleibt aber vollständig KI-unabhängig. Der Compiler und die Tests sind die Vertrauensgrenze; eine plausible Erklärung eines Modells ist kein Korrektheitsnachweis. Für menschlichen und generierten Code gelten dieselben Prüfungen für Lexer, Parser, Namen, Typen, SQL, Capabilities, Contracts, Tests und Laufzeit.

Heute verfügbare Maschinenschnittstellen

🧪 Die JSON-Ausgaben für Werkzeuge verwenden das gemeinsame Format mit schema_version: "1". Menschliche Ausgabe bleibt Standard; JSON wird nur mit --format=json angefordert:

{
    "schema_version": "1",
    "command": "check",
    "success": false,
    "diagnostics": []
}

Die Ausgabe ist deterministisch. schema_version ist verpflichtend; neue optionale Felder dürfen innerhalb einer Version ergänzt werden, inkompatible Änderungen benötigen eine neue Version. JSON gehört ausschließlich auf stdout, technische Meldungen auf stderr. Source-Spans verwenden nullbasierte UTF-8-Byte-Offsets, einsbasierte Zeilen-/Byte-Spalten und ein halb-offenes Intervall. Secrets, Zeitstempel, Zufalls-IDs, absolute maschinenabhängige Pfade und Live-Datenbankinhalte gehören nicht in diese Ausgaben.

Kanonische Quellformatierung

✅ zelyra fmt <file.zyl> erzeugt nach erfolgreichem Lexen und Parsen eine deterministische Quellformatierung. zelyra fmt <file.zyl> --check schreibt keine Dateien und liefert einen Fehlercode, wenn eine Änderung nötig wäre; damit kann CI kanonischen Quellcode erzwingen.

zelyra fmt examples/fibonacci.zyl
zelyra fmt examples/fibonacci.zyl --check

Der Formatter bewahrt Zeilenkommentare und behandelt SQL- und HTML-Blöcke als opaken Quelltext. Er ist idempotent: Ein bereits formatiertes Dokument erzeugt byte-identisch dieselbe Ausgabe.

Typisierte Lücken (Typed Holes)

✅ Ausdrucks-Typed-Holes mit _ sind als erste sichere Stufe verfügbar. Der Compiler meldet Kontexttyp, sichtbare Werte und Funktionen, aktive Capabilities, Contract-Pflichten und Source-Span:

fn double(x: Int) -> Int {
    return _
}

zelyra check meldet die Diagnose E-HOLE-001 mit dem erwarteten Typ Int und den sichtbaren Bezeichnern. Baubare Befehle (build, run, serve) lehnen unvollständigen Code vor Lowering und Ausführung ab. Lücken in Deklarationskontexten bleiben geplant.

Strukturierte Projektübersicht

✅ context ist schreibgeschützt und verbindet sich nicht mit MariaDB, nutzt kein Netzwerk, führt keine E-Mail oder Jobs aus und gibt keine Geheimnisse aus:

zelyra context examples/auth_crud_api.zyl --format=json

Sie meldet deklarierte Funktionen, Tabellen, SQL-Abfragen, CRUD-Ressourcen, Formulare, APIs und Source-Spans.

Deterministische Wirkungsanalyse

🧪 Quelltextabhängigkeiten eines Programms lassen sich deterministisch prüfen:

zelyra impact examples/auth_crud_api.zyl --format=json
zelyra impact examples/auth_crud_api.zyl --symbol table:customers --format=json

Die Wirkungsantwort meldet quelltextbasierte Tabellen, SQL, Formulare, CRUD- Ressourcen, Views, APIs, Berechtigungen, Contracts und eine deterministische references-Kantenliste für bekannte Beziehungen. Jede bekannte Kante enthält Quelle, Ziel, Art und Quelltextspanne. E-Mail-, Job-, Test- und Live-Schemaauswirkungen bleiben ausdrücklich leer oder nicht verfügbar; der Befehl verbindet sich nie mit MariaDB.

Mit --symbol <kind:name> kann die Ausgabe auf einen bekannten Knoten wie table:customers fokussiert werden. Die fokussierte Antwort enthält nur direkt verbundene Referenzen und zugehörige Knoten-IDs. Unbekannte Knoten liefern E-IMPACT-001 und einen Exit-Code ungleich null.

Atomare semantische Änderungen

🧪 Eine validierte Symbol-Umbenennung kann ohne Änderung des Quelltexts als Vorschau berechnet werden:

{
  "schema_version": "1",
  "entry": "examples/fibonacci.zyl",
  "expected_source_fingerprint": "fnv1a64:18f35ecb3e2f99c4",
  "operations": [
    {"kind": "rename", "symbol": "function", "from": "fibonacci", "to": "fib"}
  ]
}

Als change.json speichern und ausführen:

zelyra edit --format=json change.json

Die Anfrage ist versioniert und darf nur auf eine existierende .zyl-Datei innerhalb der aufgelösten Zelyra-Projektwurzel zeigen. Quelltext vor und nach der Änderung muss die Compilerprüfungen bestehen. Das Ergebnis meldet die genauen Token-Spans und einen deterministischen Quelltext-Fingerprint.

Für --apply muss die Anfrage den Fingerprint aus der Vorschau enthalten; so wird eine zwischenzeitlich geänderte Datei nicht überschrieben (Stale-Source- Schutz). Ohne den ausdrücklichen --apply-Schalter bleibt es eine reine Vorschau:

zelyra edit --format=json --apply change.json

Vor dem atomaren Ersetzen wird der Quelltext erneut geparst und vollständig geprüft; ein ungültiger oder semantisch unsicherer Vorschlag kann daher nicht geschrieben werden.

Umbenennungen von Funktionen, Typen und Records sind AST-basiert: Deklarationen und bekannte Referenzen werden umbenannt, während lokale Bindungen mit demselben Namen unverändert bleiben. Tabellen-, View-, Form- und CRUD-Deklarationen sowie ihre strukturierten Referenzen werden ebenfalls unterstützt. Tabellenumbenennungen aktualisieren geprüfte SQL-Tabellenpositionen (FROM, JOIN, INTO, UPDATE), lassen aber Literale, Kommentare, Parameter und HTML unverändert. Komponenten-Umbenennungen aktualisieren die Deklaration sowie bekannte öffnende und schließende Komponententags in HTML-Bodies.

Sicherheitsgrenze und Benchmark

KI-Werkzeuge dürfen nicht unbemerkt Capabilities hinzufügen, Berechtigungen erweitern, destruktives SQL ausführen, Diagnosen abschwächen, Tests deaktivieren oder Geheimnisse ausgeben. Destruktive Schemaänderungen und sicherheitsrelevante Änderungen brauchen eine sichtbare menschliche Freigabe. Zelyra sendet keinen Quelltext automatisch an externe KI-Dienste; geplante Integrationen sollen offen, lokal nutzbar, herstellerneutral und versioniert sein.

Der neue KI-Autorenschaftsbenchmark ist eine Spezifikation in docs/benchmarks/ai-authoring.de.md. Er soll mit versionierten Fixtures und identischen Aufgaben unter anderem Erstversuchskompilierung, Korrekturschleifen, Zeit bis zu bestandenen Tests, Tokens, Sicherheitsfehler, übersehene Abhängigkeiten, unsichere Schemaänderungen und menschlichen Prüfaufwand messen. Es gibt noch keine veröffentlichten Vergleichsergebnisse. Ein Secret-Leak oder eine nicht freigegebene destruktive Änderung bleibt ein Sicherheitsfehler und wird nicht durch vermeintliche Produktivität aufgewogen.

24. Verbindliche Quellen und Compiler-Prüfung (Source Authority)

Grundsatz: Zelyra ist eine eigenständige Sprache. Parser und geprüfte Tests entscheiden, was existiert.

Bei Widersprüchen gilt immer folgende verbindliche Reihenfolge:

  1. Formale Sprachspezifikation und Phasendokumente
  2. Compiler-Code: Lexer-, AST-, Parser-, Namensauflösungs-, Typprüfungs- und semantischer Code in den Crates lexer, parser, ast, hir, cli, runtime, database, web und forms
  3. Offizielle automatisierte Sprach- und Integrationstests: Workspace-Tests (cargo test --workspace), Machine-Interface-Tests und E2E-Shellskripte in tests/
  4. Die offizielle Standardbibliothek: (sobald eigenständig strukturiert)
  5. Offizielle Zelyra-Beispiele: .zyl-Dateien in examples/, die mit dem aktuellen Compiler erfolgreich verifiziert wurden
  6. Dokumentation und Handbuch

Wichtige Invarianten für Entwickler und KI-Assistenten

25. Anwendungs-Mail und SMTP

Anwendungs-Mail wird in derselben MariaDB-Transaktion wie eine Geschäftsänderung eingereiht. Der Webrequest wartet nicht auf SMTP. Ein separater Worker stellt fällige Nachrichten zu.

Projekt und Transport konfigurieren

[capabilities]
email = true
database = true

[network]
allowed_hosts = ["smtp.example.test"]

ZELYRA_SMTP_HOST=smtp.example.test
ZELYRA_SMTP_SECURITY=starttls
ZELYRA_SMTP_PORT=587
ZELYRA_SMTP_FROM="Zelyra <noreply@example.test>"
ZELYRA_SMTP_USERNAME=app-user
ZELYRA_SMTP_PASSWORD=durch-ein-secret-ersetzen

implicit_tls ist der Standard und verwendet Port 465; starttls verwendet Port 587. Zertifikats- und Hostnamenprüfung bleiben aktiv. Optional ergänzt ZELYRA_SMTP_CA_CERT ein PEM-Wurzelzertifikat aus einer regulären Datei ohne Symlink bis 128 KiB. local_plaintext ist nur für Loopback ohne Zugangsdaten zulässig. Der genaue SMTP-Host muss in der Allowlist stehen. Speichere Zugangsdaten in der lokalen .env oder Prozessumgebung; übernimm sie nicht in die Versionsverwaltung.

Nachrichten einreihen

Speichere folgendes Beispiel als main.zyl in einem entsprechend konfigurierten MariaDB-Projekt:

pub fn deliver_mail(event_id: String, event_type: String, payload_json: String) -> Bool uses Email {
  if event_type == "zelyra.mail.send" {
    match mail_deliver(event_id, payload_json) {
      Ok(_) => { return true }
      Err(_) => { return false }
    }
  }
  return false
}

fn main() uses Email, Database(write) {
  transaction {
    mail_queue(
      "customer@example.test",
      "Your Zelyra order",
      "Your order has been recorded.",
      "<p>Your order has been recorded.</p>"
    )
  }
}

mail_queue(to, subject, text, html?) ist eine Anweisung direkt innerhalb von transaction. Die Funktion benötigt Email und Database(write). Die API prüft Header-Injection und Größen; Argumente müssen Werte oder nebenwirkungsfreie String-Ausdrücke sein. Bei einer zurückgerollten Transaktion bleibt keine zugehörige Mail eingereiht. HTML-Inhalte musst du vor dem Einreihen passend escapen, wenn sie nicht vertrauenswürdig sind.

Outbox und Worker

zelyra outbox setup main.zyl
zelyra run main.zyl
zelyra outbox list main.zyl --limit 25
zelyra outbox run main.zyl --handler zelyra.mail.send=deliver_mail --once

Richte die Outbox vor dem ersten Programmlauf ein. --once verarbeitet einen fälligen Eintrag; ohne diese Option verarbeitet der Worker zugeordnete fällige Ereignisse, bis keines mehr ansteht. mail_deliver(event_id, payload_json) liefert einen Result; der Handler bestätigt Erfolg mit true und erlaubt Wiederholung mit false. Der SMTP-Transport hat ein Zeitlimit von fünf Sekunden und gibt redigierte Fehler aus.

Zustellung erfolgt mindestens einmal. Nach SMTP-Annahme und vor Outbox-Quittierung kann ein Worker ausfallen; dadurch sind Duplikate möglich. Die Ereignis-ID wird als stabile Nachrichten-ID verwendet, garantiert aber keine einmalige Zustellung. Die dokumentierte API unterstützt Text-/HTML-Alternativen über die MariaDB-Outbox. Benannte Templates, Anhänge und PostgreSQL-Mail-Outbox sind nicht als verfügbare API belegt. Siehe die Mail-Referenz.

Persistente Passwort-Reset-Quoten

Zur Härtung gegen Brute-Force- und Denial-of-Service-Angriffe speichert Zelyra Passwort-Reset-Anfragen neustartsicher in der Tabelle password_reset_limits. Die Drosselung bleibt auch bei Prozessneustarts aktiv. Abgelaufene Zeitfenster werden in Batch-Zyklen automatisch aufgeräumt, während Diagnoseausgaben für Operatoren strikt sanitisiert bleiben, um keine E-Mail-Adressen oder Tokens im Protokoll preiszugeben.

26. Mandantengebundene Benachrichtigungen

Das In-App-Zentrum funktioniert ohne SMTP. Es verwendet authentifizierte Mandantenzugehörigkeit, eine gemeinsame Benachrichtigungstabelle und eine mandantengebundene CRUD-Ressource. Der aktive Mandant begrenzt Listen, direkte Zugriffe und den ungelesenen Zähler. Abgelaufene und archivierte Einträge werden ausgeblendet.

Vollständiges MariaDB-Beispiel

Speichere das Beispiel in einem MariaDB-Projekt mit aktivierten Datenbank-, Web-, CRUD- und Auth-Funktionen. Richte Schema, Benutzer, Passwort-Hash, Mandantenzugehörigkeit und Berechtigungen ein, bevor du die Anwendung im Browser verwendest:

# Tenant-scoped notification inbox starter for MariaDB projects.
# Every generated notification route verifies the authenticated membership.

auth users {
    table: users
    sessions: auth_sessions
    permissions: user_permissions
    memberships: tenant_memberships
}

table users {
    id: Id primary auto
    email: Email required unique
    password_hash: String(255) required
    active: Bool default true
}

table auth_sessions {
    id: Id primary auto
    user: User required
    token_hash: String(64) required unique
    expires_at: Timestamp required
}

table user_permissions {
    id: Id primary auto
    user_id: Id required
    permission: String(100) required
}

table tenant_memberships {
    id: Id primary auto
    user_id: Id required
    tenant_id: Id required
    active: Bool required
}

table notifications {
    id: Id primary auto
    tenant_id: Id required
    title: String(160) required
    message: String(4000) required
    category: String(40) required
    read_at: Timestamp?
    archived_at: Timestamp?
    expires_at: Timestamp?
    created_at: Timestamp default now
}

crud Notification -> notifications {
    title: "Notifications"
    tenant: tenant_id
    unread: read_at
    expires: expires_at
    requires auth
    permits "notifications.view"
    permits create "notifications.manage"
    permits edit "notifications.manage"
    permits delete "notifications.manage"

    soft_delete {
        column: archived_at
    }

    list {
        title
        category
        created_at
        read_at
    }

    search {
        title
        message
    }

    filter {
        category
        read_at
    }

    view {
        fields {
            title
            message
            category
            read_at
            expires_at
        }
    }
}

table notification_preferences {
    id: Id primary auto
    tenant_id: Id required
    email_enabled: Bool default false
    retention_days: Int default 90
    updated_at: Timestamp default now
}

crud NotificationPreference -> notification_preferences {
    title: "Notification preferences"
    tenant: tenant_id
    requires auth
    permits "notifications.manage"
    list {
        email_enabled
        retention_days
        updated_at
    }
    view {
        fields {
            email_enabled
            retention_days
        }
    }
}

fn main() {
}

tenant: tenant_id bindet die Ressource an den aktiven Mandanten und seine Mitgliedschaft. unread: read_at stellt den ungelesenen Zähler bereit; expires: expires_at blendet abgelaufene Einträge aus. soft_delete archiviert über archived_at. notifications.view erlaubt Lesen, notifications.manage schützt Verwaltung und Änderungen. Ein Tenant-Feld allein ohne die Auth-/Mitgliedschaftskonfiguration ist keine Mandantenisolierung.

Lesestatus, Aufbewahrung und Mail

read_at ist ein Zeitstempel am Benachrichtigungseintrag. Über die Empfängerbindung (recipient: user_id) wird sichergestellt, dass Benachrichtigungen nur für den berechtigten Benutzer sichtbar sind. Persönliche Lesebestätigungen werden mit CSRF-Schutz und atomarem Audit-Logging quittiert. Die Einstellungstabelle speichert email_enabled und retention_days. Ablauf wird beim Lesen berücksichtigt; Archivierung ist keine physische Löschung. Das Beispiel zeigt den vorhandenen Umfang.

Lokales TOTP-MFA

Für mehrstufige Authentifizierung unterstützt Zelyra zeitbasierte Einmalkennwörter (TOTP nach RFC 6238). Die geheimen Schlüssel werden mit AES-256-GCM verschlüsselt in der Datenbank abgelegt. Einmalige Wiederherstellungscodes werden mit Argon2id sicher gehasht. Das System wehrt Token-Wiederholungsangriffe (Replay Defense) sowie Rennbedingungen ab und sperrt Konten nach fünf aufeinanderfolgenden Fehlversuchen automatisch temporär (HTTP 429).

27. Sprache, Laufzeit und PDF-Mail

Dieses Kapitel dokumentiert die Spracherweiterungen aus Zelyra 1.0.7. Die Version erweitert Sprache und Runtime für gut prüfbare Businesslogik und ergänzt eine lokale, serverseitige Text-PDF-Pipeline für Views und transaktionale E-Mail-Anhänge.

Wertliefernde Ausdrücke und Record-Updates

Ein if-Ausdruck liefert in beiden Zweigen denselben typgeprüften Wert. Records lassen sich mit ..old funktional kopieren und selektiv aktualisieren:

fn invoice_label(paid: Bool) -> String {
    return if paid { "Bezahlt" } else { "Offen" }
}

struct Customer {
    id: Int
    name: String
    active: Bool
    version: Int
}

fn activate_customer(c: Customer) -> Customer {
    return Customer { ..c, active: true, version: c.version + 1 }
}

Typisierte Lambdas und Pipelines

Lambdas sind lexikalische Closures. Der Compiler prüft Callback-Eingaben und Ergebnisse statisch; Pipelines bleiben synchron und deterministisch:

fn calculate_tax_totals(amounts: Int[]) -> Int[] {
    return amounts
        |> filter(|a| a > 0)
        |> map(|a| a + (a * 19 / 100))
}

Verschachtelte Record-Muster, Match-Guards und Tupel

match unterstützt verschachtelte Record-Muster und boolesche Wächter (Guards). Tupel können als reguläre Rückgabewerte dienen und mehrfach destrukturiert werden:

struct Order { status: String total: Int }

fn inspect_order(order: Order) -> Tuple<String, Bool> {
    return match order {
        Order { status: "paid", total } if total >= 1000 => ("VIP-Grossauftrag", true)
        Order { status: "paid", total }                  => ("Standardauftrag", true)
        _                                                => ("Ausstehend", false)
    }
}

Begrenzte Ausführung mit Step-Budget

zelyra run datei.zyl --max-steps N begrenzt Anweisungen und Ausdrucksauswertungen über alle parallel-Zweige hinweg und meldet Überschreitungen als E-RUNTIME-001 an der Quellstelle:

zelyra run main.zyl --max-steps 5000

Serverseitiges Text-PDF und transaktionale Outbox-E-Mail

render_pdf("InvoicePrint", invoice) rendert eine deklarierte View lokal in Bytes. Innerhalb derselben Datenbanktransaktion kann mail_queue einen PDF-Anhang in der MariaDB-Outbox einreihen:

fn send_invoice(recipient: String, invoice: Invoice) uses Email, Database(write) {
    transaction {
        mail_queue(
            recipient,
            "Rechnung " + invoice.number,
            "Ihre Rechnung ist beigefügt.",
            "invoice-" + invoice.number + ".pdf",
            render_pdf("InvoicePrint", invoice)
        )
    }
}

28. Systemd-Dienste, Scheduler und Jobs

Zelyra integriert Betriebssystemdienste, permanente Hintergrund-Zeitpläne und asynchrone Jobs direkt in die Toolchain, ohne externe Cron-Dämonen oder unzuverlässige Skriptschleifen.

Linux-systemd-Dienstverwaltung

Mit zelyra service wird für ein Projekt ein dedizierter Linux-systemd-Benutzerdienst eingerichtet. Der Service verwendet einen fest konfigurierten Port:

# Dienst auf festem Port 8080 installieren
zelyra service install --port 8080

# Status des Dienstes und HTTP-Erreichbarkeit prüfen
zelyra service status

# Dienst neu starten (wartet auf lokale Socket-Erreichbarkeit)
zelyra service restart

# Port unterbrechungsfrei und mit atomarem Rollback ändern
zelyra service change --port 8081

# Dienst stoppen und Unit-Datei entfernen
zelyra service remove

Ist der angegebene Port belegt, schlägt die Installation fehl (fail-closed). Zelyra weicht niemals stillschweigend auf einen anderen Port aus. Bei service change wird die alte Unit erst dann überschrieben und der neue Dienst gestartet, wenn der Zielport frei ist; bei Fehlern wird der vorherige Zustand automatisch wiederhergestellt.

Residente Zeitpläne und MariaDB-Outbox-Jobs

Zeitpläne werden deklarativ im Zelyra-Quellcode definiert:

schedule weekly_report {
    cron: "0 8 * * 1"
    timezone: "Europe/Berlin"
    command: generate_reports
}

Der residente Scheduler läuft ausschließlich innerhalb des aktiven Zelyra-Projektdienstes. An jeder Minutengrenze prüft er anstehende Ausführungen und reiht geplante Jobs transaktional in die MariaDB-Outbox ein. Ein serieller Worker übernimmt anstehende Aufgaben mit erneuerbaren Leases und begrenzten Wiederholungen.

# Alle anstehenden und ausgeführten Jobs des Projekts einsehen
zelyra schedule jobs main.zyl

# Status des residenten Schedulers abfragen
zelyra schedule status main.zyl

# Zeitpläne als crontab-kompatible Vorschau exportieren (z. B. für externe Systeme)
zelyra schedule export main.zyl --format cron

29. Kanonische Projektstruktur und Vertical Slices

Ab Version 1.2.13 unterstützt Zelyra ein verbindliches, feature-orientiertes Standard-Projektlayout (Vertical Slice Architecture), das in Version 1.3.0 zum Standard avanciert. Es trennt Routing strikt von Geschäfts- und Datenmodell.

Das Standardlayout anlegen

zelyra new mein-erp --layout standard

Ein Projekt mit Standard-Layout besitzt folgende verbindliche Struktur:

mein-erp/
├── zelyra.toml                 # Projekt-Manifest (layout = "standard")
├── schema/                     # Single Source of Schema
│   └── tables.zyl              # Tabellen, Indizes, Relationen
├── domain/                     # Fachdomänen (Vertical Feature Slices)
│   ├── invoices/               # Feature-Modul Rechnungen
│   │   ├── actions.zyl         # Geschäftsvorfälle & Rechenregeln
│   │   └── views.zyl           # UI-Komponenten & Ansichten
│   └── customers/              # Feature-Modul Kunden
│       ├── actions.zyl
│       └── views.zyl
├── routes/                     # Schlanke HTTP-Gatekeeper
│   ├── web.zyl                 # Web-Routen & Formular-Handling
│   └── api.zyl                 # REST-/JSON-Endpunkte
├── public/                     # Statische Dateien (vom Server direkt ausgeliefert)
└── assets/                     # Web-Assets (fließen in das Binary ein)
    ├── css/
    └── js/

Namespace-Importe und strikte Architekturprüfung

Im Standardlayout löst Zelyra Importe direkt über die Namensraumwurzeln auf:

use schema::tables::*
use domain::invoices::actions as invoice_ops

Wird in der zelyra.toml der Schalter strict_architecture = true aktiviert, erzwingt der Zelyra-Linter folgende Kardinalregel:

Keine direkten Datenbankmutationen in Routen-Dateien (routes/*.zyl).

Schreibende Operationen (insert, update, delete) innerhalb von Routen führen zum Abbruch mit dem Compilerfehler E-ARCH-001. Fachlogik muss in domain/<feature>/actions.zyl implementiert und getestet werden.

# Migrationsvorschau auf das Standardlayout prüfen (schreibgeschützt, verändert keine Dateien)
zelyra migrate-layout --check main.zyl

30. Erweiterbare CRUD- und TableView-Seiten

Zelyra 1.2.15 führt typgeprüfte Erweiterungspunkte für automatisch generierte CRUD-Seiten und Tabellenansichten ein. Entwickler können Standard-Masken flexibel anpassen, ohne das sichere Fundament aus Validierung, Berechtigungen und CSRF-Schutz aufgeben zu müssen.

Create- und Edit-Seiten anpassen

Über crud.view.create und crud.view.edit lassen sich Seitentitel, Schaltflächentexte und ergänzende Inhaltsblöcke vor oder nach dem Formular einbinden:

crud KundenVerwaltung for Customer {
    view create {
        title: "Neuen Kunden registrieren"
        submit_label: "Kundenkonto anlegen"
        help: "Bitte prüfen Sie die USt-IdNr. vor dem Speichern."
    }
    view edit {
        title: "Kundendaten aktualisieren"
        submit_label: "Änderungen übernehmen"
    }
}

Zusätzliche Inhalte verwenden denselben sicheren Template-Kontext und unterliegen voller XSS-Escaping- und Typprüfung. Scheitert eine Formularvalidierung, bleiben die ergänzten Inhalte und Hinweistexte zusammen mit den Fehlermeldungen erhalten.

Erweiterte TableView-Listen und Zeilenaktionen

Tabellenansichten (tableview) können mit Kopf- und Fußbereichen sowie individuellen Zeilenaktionen versehen werden:

tableview RechnungsListe for Invoice {
    columns: [number, customer_name, total_gross, status]
    row_actions: [
        action "Details" -> "/invoices/show/{id}",
        action "PDF" -> "/invoices/{id}/pdf"
    ]
}

Die Zeilenaktionen erzeugen saubere, auditierbare URLs. Sicherheitsprüfungen und Mandanten-Filter bleiben vollständig wirksam.

31. AST-, MIR- und Bytecode-Ausführung

Stand des stabilen Releases 1.2.39: Der AST-Interpreter bleibt der Standard-Ausführungspfad. MIR und Bytecode unterstützen ausgewählte Abläufe; vollständige Web-/Laufzeitparität bleibt offene Arbeit auf dem Weg zu 1.3.0. Dieser Abschnitt beschreibt Architektur und Grenzen. Er behauptet keinen allgemeinen Leistungsvorteil oder abgeschlossene Enterprise-Garantien.

Quellcode (.zyl)
      │
      ▼
Lexer & Parser
      │
      ▼
AST mit Source-Spans
      │
Gemeinsame statische Prüfungen (Types, Contracts, Scopes)
      │
      ├───────────────────────────────┐
      ▼                               ▼
[1. AST-Interpreter]            [2. MIR und Bytecode]
- Standard-Ausführungspfad      - Für unterstützte Abläufe verfügbar
- Quellbezogene Diagnostik      - Geprüfte Zwischenrepräsentationen
- Vergleichsreferenz            - Paritätsprüfungen bleiben offen
  1. AST-Interpreter: Standardpfad für unterstützte Programmausführung und Referenz beim Vergleich von Backends.
  2. Typisierte MIR: Trägt geprüfte Programmdaten für unterstützte Konstrukte; der Verifier weist widersprüchliche SQL-Metadaten mit E-MIR-VERIFY-004 ab.
  3. Bytecode-VM: Führt den unterstützten Bytecode-Umfang aus. Parität wird dort getestet, wo sie implementiert ist; die Tests garantieren sie nicht für jede Sprachfunktion oder jeden Webablauf.

32. Mandantensicherheit und zusammengesetzte Fremdschlüssel

In mandantenfähigen B2B-Anwendungen darf kein Datensatz ohne Tenant-Zugehörigkeit existieren, und Fremdschlüssel dürfen niemals mandantenübergreifend referenzieren. Zelyra verankert Mandantensicherheit direkt im Tabellenschema (scoped by tenant_id: TenantId).

Deklaration von Mandantentabellen

type TenantId = Id

table customers scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    customer_number: String(50) required unique within tenant
    name: String required
}

table invoices scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    invoice_number: String(50) required unique within tenant
    customer: Customer?
    total_net: Decimal(12, 2) required default 0
    total_gross: Decimal(12, 2) required default 0
}

Automatische Integritätsgarantien auf Datenbankebene

  1. Zusammengesetzter Primärschlüssel-Schutz: Zelyra erzeugt automatisch uq_{table}_tenant_id UNIQUE (tenant_id, id).
  2. Mandantenisolierte Fremdschlüssel: Verknüpfungen zwischen mandantenisolierten Tabellen (customer: Customer?) generieren automatisch zusammengesetzte Fremdschlüssel: 
    FOREIGN KEY (tenant_id, customer_id) REFERENCES customers (tenant_id, id) ON DELETE RESTRICT
    Diese Constraints weisen mandantenübergreifende Fremdschlüsselzuweisungen auf den unterstützten Schema-Pfaden auf Datenbankebene zurück.
  3. Mandantenbezogene Eindeutigkeit: Mit unique within tenant deklarierte Felder erzeugen UNIQUE KEY (tenant_id, customer_number). Unterschiedliche Mandanten können dieselbe Belegnummer führen, innerhalb eines Mandanten sind Duplikate ausgeschlossen.
  4. Optionale Relationen und kaufmännische Dezimalzahlen: Optionale Verknüpfungen (Customer?) erzeugen typsicher BIGINT NULL. Decimal(p, s) (z. B. Decimal(12, 2)) garantiert exakte kaufmännische Rundung ohne Gleitkomma-Ungenauigkeiten.

33. Tabelleninvarianten und Validierungsregeln

Geschäftsregeln gehören direkt an die Datenstruktur. Statt Validierungsregeln in Controllern, Requests und Formularen redundant zu wiederholen, deklariert Zelyra typgeprüfte Invarianten im table-Block.

Deklaration von Tabelleninvarianten

table invoices scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    invoice_date: Date required
    due_date: Date required
    discount_days: Int required default 0

    validate {
        due_date >= invoice_date: "Das Fälligkeitsdatum muss am oder nach dem Rechnungsdatum liegen."
        discount_days >= 0: "Skontofrist darf nicht negativ sein."
    }
}

Durchsetzung in Formularen und APIs

34. Lifecycle-Guards, Policies und Master-Detail-CRUD

Revisionssicherheit (z. B. nach GoBD) verlangt, dass festgeschriebene Belege nicht mehr nachträglich verändert oder gelöscht werden dürfen. Gleichzeitig müssen komplexe Belege wie Rechnungen oder Aufträge Kopf- und Positionsdaten atomar erfassen.

Datensatzabhängige Lifecycle-Guards

table invoices scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    invoice_date: Date required
    is_locked: Bool required default false
}

crud Invoice -> invoices {
    title: "Rechnungen"

    guard edit when is_locked == true {
        error: "Festgeschriebene Rechnungen können nicht mehr bearbeitet werden (GoBD-Schutz)."
    }

    guard delete when is_locked == true {
        error: "Festgeschriebene Rechnungen dürfen nicht gelöscht werden."
    }
}

Zusammenspiel mit GoBD, Prüfsummen und Capabilities

Reale Geschäftsanwendungen erfordern neben Lifecycle-Sperren weitere Bausteine, die Zelyra über die Standardbibliothek und Capabilities bereitstellt:

  1. Kryptografische Prüfsummen (hash_sha256): Die Funktion hash_sha256(text: String) -> String aus der Standardbibliothek berechnet den SHA-256-Hash eines Strings. Sie dient dazu, den Inhalt eines Belegs bei der Festschreibung kryptografisch zu fixieren: 
    fn beleg_hash(beleg_nr: String, brutto: Decimal) -> String {
    return hash_sha256(beleg_nr + "#" + brutto)
}
  2. Revisionssichere Zeitstempel (now() und uses Clock): Funktionen, die die aktuelle Zeit ermitteln, müssen die Capability Clock deklarieren (fn festschreiben(...) uses Clock). Dadurch bleibt Zeitverhalten in Unittests deterministisch überprüfbar und reproduzierbar.
  3. Beleg-PDFs und Outbox-Mail (render_pdf und mail_queue): Über render_pdf("RechnungsDruck", invoice) wird eine View serverseitig in PDF-Bytes umgewandelt. Innerhalb einer MariaDB-transaction reiht mail_queue(to, subject, text, filename, pdf_bytes) den Beleg atomar in die Outbox ein.
  4. CRUD-Actions: Seit 1.2.28 unterstützen CRUD-Actions typisierte Handler, Datensatz- und Sitzungsdaten sowie geprüfte Guards im vorhandenen serverseitigen Transaktionskontext. Zulässige Ausdrücke und Effekte folgen der dokumentierten Action-Syntax; Actions sind keine beliebigen Zelyra-Programme.

Transaktionale Master-Detail-CRUD-Formulare (has_many)

Mit has_many deklarieren CRUD-Ressourcen direkte 1:N-Kinddatensammlungen:

table invoice_items scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    invoice: Invoice required on_delete cascade
    position: Int required
    description: String(160) required
    total_net: Decimal(12, 2) required
    total_gross: Decimal(12, 2) required

    validate {
        total_gross >= total_net: "Bruttobetrag darf nicht kleiner als der Nettobetrag sein."
    }
}

crud Invoice -> invoices {
    title: "Rechnungen"

    view {
        fields { invoice_date }
        form {
            title: "Rechnung"
            submit: "Rechnung speichern"
        }
    }

    has_many items: InvoiceItem {
        foreign_key: invoice_id
        order_by: position asc
        cascade: delete
        aggregates {
            net_amount: sum(total_net)
            tax_amount: sum(total_gross - total_net)
            gross_amount: sum(total_gross)
        }
    }
}
  1. Serverseitiges Rendering: Kindzeilen werden serverseitig in HTML generiert. Zeilen können ohne Client-JavaScript hinzugefügt oder entfernt werden.
  2. Atomare Transaktion: Kopfdaten, Kindpositionen und berechnete Aggregate (aggregates) werden in einer einzigen Datenbanktransaktion gespeichert. Ein Fehler in einer Position rollt den gesamten Vorgang zurück.
  3. Automatische Aggregation: Summenfelder wie net_amount oder gross_amount werden serverseitig aus den Kindzeilen berechnet und atomar im Kopfsatz aktualisiert.

Mehrere Kind-Sammlungen pro CRUD-Ressource (ab Zelyra 1.2.24)

Seit Zelyra 1.2.24 können generierte CRUD-Anlegen- und Bearbeiten-Formulare mehrere direkte has_many-Sammlungen desselben Elternsatzes verwalten (z. B. Positionen und Dateianhänge einer Rechnung in einem gemeinsamen Formular):

table invoices {
    id: Id primary auto
    reference: String(100) required
    invoice_date: Date required
    net_amount: Decimal(12, 2) required default 0
    gross_amount: Decimal(12, 2) required default 0
}

table invoice_items {
    id: Id primary auto
    invoice: Invoice required on_delete cascade
    position: Int required
    description: String(160) required
    total_net: Decimal(12, 2) required
    total_gross: Decimal(12, 2) required

    validate {
        total_gross >= total_net: "Line gross amount cannot be below its net amount."
    }
}

table invoice_attachments {
    id: Id primary auto
    invoice: Invoice required on_delete cascade
    file_name: String(255) required
    size_bytes: Int required

    validate {
        size_bytes > 0: "Attachment size must be positive."
    }
}

crud Invoice -> invoices {
    title: "Rechnungen mit Positionen und Anhängen"

    view {
        fields { reference invoice_date }
        form {
            title: "Rechnung"
            submit: "Rechnung speichern"
        }
    }

    has_many items: InvoiceItem {
        foreign_key: invoice_id
        order_by: position asc
        cascade: delete
        aggregates {
            net_amount: sum(total_net)
            gross_amount: sum(total_gross)
        }
    }

    has_many attachments: InvoiceAttachment {
        foreign_key: invoice_id
        order_by: file_name asc
        cascade: delete
    }
}

35. Das Zelyra-Ökosystem: Pakete, Module und Einstellungen

Das Zelyra-Modul- und Paketökosystem ermöglicht die saubere Modularisierung von Anwendungen in wiederverwendbare, unabhängig testbare und kryptografisch prüfbare Komponenten. Es verbindet Offline-First-Prinzipien mit strikter Typisierung und Compiler-Garantien.

Grundlagen und Philosophie des Zelyra-Ökosystems

  1. Offline-First und Deterministisch: Ein Zelyra-Projekt baut und prüft vollständig offline. Es gibt keine impliziten Downloads beim Kompilieren (zelyra check / zelyra run), keine unkontrollierten Netzwerkzugriffe und keine Ausführung beliebiger Build-Skripte von Drittanbietern.
  2. Integrität und Lockfile: Jede Abhängigkeit wird mit einer kryptografischen SHA-256-Prüfsumme in zelyra.lock fixiert. Änderungen an Quellcode oder Paketmanifest werden vom Compiler sofort erkannt und erfordern eine explizite Aktualisierung (zelyra package lock --update).
  3. Kryptografisches Vertrauensmodell (Ed25519): Für die Weitergabe und Registrierung nutzt Zelyra signierte .zpkg-Quellarchive. Ein Archiv wird mit dem privaten Ed25519-Schlüssel eines Herausgebers signiert. Empfänger hinterlegen autorisierte öffentliche Schlüssel in zelyra.trust.toml. Ohne explizites Vertrauen verweigert Zelyra die Installation.
  4. Compiler-Effektobergrenzen (effects): Ein Paket kann im Manifest deklarieren, welche Capabilities seine Funktionen maximal beanspruchen dürfen (z. B. effects = ["Database(read)"] oder effects = [] für rein rechnerische Bibliotheken). Überschreitet eine Funktion im Paket diese Obergrenze, meldet der Compiler einen Fehler.

Ein neues Modul erstellen: zelyra module init

Ein neues Modulpaket wird mit dem CLI-Befehl zelyra module init initialisiert:

zelyra module init packages/finanz_tools --name finanz_tools --version 0.1.0

Der Befehl erstellt die Standardstruktur ohne Netzwerkverbindung und ohne bestehende Dateien zu überschreiben:

packages/finanz_tools/
├── zelyra.toml
├── README.md
└── src/
    └── lib.zyl

Das Paketmanifest: zelyra.toml

Das Manifest zelyra.toml deklariert die Identität, Versionskompatibilität und Effektobergrenzen des Pakets:

[package]
name = "finanz_tools"
version = "0.1.0"
entry = "src/lib.zyl"
zelyra = ">=1.1.0, <2.0.0"
effects = ["Database(read)"]

[settings.api_timeout]
type = "Int"
required = false
default = 15
description = "Zeitlimit für externe Abfragen in Sekunden"

[settings.api_token]
type = "String"
required = true
secret = true
description = "Geheimer API-Schlüssel für Finanzdaten"

Modulcode schreiben und exportieren

Funktionen, Records und Enums, die von außen erreichbar sein sollen, müssen mit dem Schlüsselwort pub exportiert werden:

pub record TaxResult {
    net: Decimal,
    tax: Decimal,
    gross: Decimal,
}

pub fn calculate_tax(net: Decimal, rate: Decimal) -> TaxResult
    requires { net >= 0 && rate >= 0 }
    ensures { result.gross >= result.net }
{
    let tax = (net * rate) / 100
    return TaxResult {
        net: net,
        tax: tax,
        gross: net + tax,
    }
}

Nicht als pub deklarierte Deklarationen bleiben paketintern geschützt. Verträge (requires, ensures) werden beim Import vollständig vom Compiler geprüft.

Typisierte Moduleinstellungen (Settings)

Zelyra trennt Paket-Konfigurationsschemata strikt von Anwendungsdaten und Geheimnissen:

  1. Schemadeklaration: Das Schema wird im Paketmanifest unter [settings.<feld>] beschrieben. Unterstützt werden String (bis 4 KiB), Bool, Int und Float. Geheimnisse deklarieren secret = true und dürfen keinen Standardwert besitzen.
  2. Anwendungs-Konfiguration in zelyra.settings.toml: Werte liegen im Workspace der Hauptanwendung, getrennt von zelyra.toml, damit sich Paketprüfsummen nicht verändern: 
    [package_settings."packages/finanz_tools"]
api_timeout = 30
api_token = { env = "FINANZ_API_TOKEN" }
    Geheimnisse werden ausschließlich über { env = "ENV_VAR" } referenziert. Die Zelyra-Laufzeit liest den Wert aus der Prozessumgebung und verhindert die Protokollierung in Fehlermeldungen oder Logs.
  3. Abruf im Zelyra-Code: Paketfunktionen lesen konfigurierte Werte typisiert über die interne generische Funktion module_setting<T>: 
    fn get_timeout_seconds() -> Int {
    let timeout = module_setting<Int>("api_timeout")
    return timeout
}
  4. Verwaltung über Web und Studio:
    • CLI-Prüfung: zelyra module settings check main.zyl prüft Typen, Pflichtfelder und die Verfügbarkeit von Umgebungsvariablen.
    • Zelyra Studio: Unter Moduleinstellungen bietet Studio einen revisionsgesicherten Einstellungseditor mit .zelyra.settings.lock.
    • Laufzeit-Webseite: Ist in einer Anwendung Authentifizierung aktiv und admin_permission definiert, steht unter /__zelyra/module-settings eine CSRF-geschützte Webverwaltung für Administratoren bereit.

Einbinden in eine Zelyra-Anwendung

Um ein Modul in einer Hauptanwendung zu verwenden, wird es im Anwendungsmanifest zelyra.toml unter [dependencies.<alias>] eingetragen:

[package]
name = "meine_anwendung"
version = "1.0.0"
entry = "main.zyl"
zelyra = ">=1.2.0"

[dependencies.finanz]
path = "packages/finanz_tools"
version = "^0.1"

Im Quellcode erfolgt der Import über den Namensraum-Präfix pkg:<alias>:

import "pkg:finanz" as finanz

fn main() {
    let result = finanz::calculate_tax(200.0, 19.0)
    print(result.gross)
}

Nach dem Hinzufügen der Abhängigkeit wird das Lockfile synchronisiert und geprüft:

zelyra package lock .
zelyra check main.zyl

Modul-Inspektion, Planung und Bundling

Zelyra stellt spezialisierte Befehle zur Analyse und Distribution von Modulen bereit:

  1. Modul-Katalog anzeigen (module list): 
    zelyra module list main.zyl
zelyra module list main.zyl --format json
    Listet alle Quellmodule, Importaliase, öffentlichen Exporte, Prüfsummen, Effektobergrenzen und Einstellungs-Schemas deterministisch auf.
  2. Abhängigkeitsgraph analysieren (module plan): 
    zelyra module plan main.zyl pkg:finanz
    Berechnet den statischen Quellabschluss für das angegebene Modul und meldet fehlende oder zirkuläre Referenzen vor dem Bauen.
  3. Modul bündeln (module bundle): 
    zelyra module bundle main.zyl pkg:finanz --output ./dist/finanz-bundle
    Erstellt ein eigenständiges Quellbundle mit isolierten Paketabhängigkeiten und neu berechnetem Lockfile, das offline und portabel deployt werden kann.

Signierte Pakete, Registry und Transaktionale Wiederherstellung

Für teams- und organisationsübergreifende Verteilungen stellt Zelyra kryptografische Paketwerkzeuge bereit:

36. CSS-Designsystem und Oberflächengestaltung für CRUD und TableViews

Zelyra verfolgt beim Frontend denselben Grundsatz wie bei Sprache und Datenbank: Konstruierte Sicherheit ohne Ballast. Statt schwergewichtige JavaScript-Build-Pipelines, Node.js-Abhängigkeiten oder npm-Pakete vorauszusetzen, liefert Zelyra ein integriertes, performantes CSS-Designsystem (zelyra-ui.v1.css), das direkt vom integrierten Webserver ausgeliefert wird.

Dieses Kapitel beschreibt die Architektur des Zelyra-UI-Systems, alle verfügbaren Design-Tokens und Klassen sowie konkrete, produktionsreife CSS-Rezepte zur individuellen Gestaltung von CRUD-Seiten, TableViews, Master-Detail-Formularen und Filtern.

1. Architektur des Zelyra-UI-Designsystems

Das Zelyra-Designsystem basiert auf modernen Webstandards und modernen CSS-Kaskadierungs-Ebenen (CSS Cascade Layers @layer).

┌────────────────────────────────────────────────────────────────────────┐
│                        CSS Cascade Layers                              │
│                                                                        │
│  @layer reset         Browser-Normalisierung & Box-Sizing              │
│       ↓                                                                │
│  @layer base          Root-Variablen, Typografie, Standardelemente     │
│       ↓                                                                │
│  @layer theme         Farbschemata (Light, Dark, System), Dichte       │
│       ↓                                                                │
│  @layer layout        App-Shell, Grids, Container, Scrollbereiche      │
│       ↓                                                                │
│  @layer components    Karten, Buttons, Badges, Tabellen, Formulare     │
│       ↓                                                                │
│  @layer utilities     Hilfsklassen (Abstände, Textausrichtung)         │
│       ↓                                                                │
│  @layer overrides     Zelyra-Standardseiten (CRUD, TableViews)         │
│       ↓                                                                │
│  [Projekt-CSS]        Eigene zelyra.theme.css (höchste Priorität)      │
└────────────────────────────────────────────────────────────────────────┘

Der Root-Selektor und Spezifität

Alle Standardstile von Zelyra UI sind mit dem CSS-Pseudoselektor :where(html[data-z-ui]) gekapselt:

:where(html[data-z-ui]) .z-table {
  width: 100%;
  border-collapse: collapse;
}

Die :where()-Pseudoklasse verleiht dem Selektor eine Spezifität von 0. Dadurch können Entwickler beliebige Zelyra-Stile in ihrer eigenen zelyra.theme.css mit gewöhnlichen Klassenselektoren (z. B. .z-table) überschreiben, ohne zu !important oder unleserlichen Selektorketten greifen zu müssen.

Einbindung von Projekt-Stylesheets

Ein Zelyra-Projekt kann projektspezifisches CSS auf zwei Wegen einbinden:

  1. Automatische Erkennung: Liegt im Wurzelverzeichnis des Projekts eine Datei namens zelyra.theme.css oder assets/css/theme.css, wird diese vom integrierten Server automatisch nach dem Zelyra-Basissystem in den <head> aller generierten Seiten injiziert.
  2. Umgebungsvariable / Konfiguration: Über die Umgebungsvariable ZELYRA_UI_STYLESHEET=/pfad/zu/style.css oder den CLI-Parameter --stylesheet kann ein beliebiger alternativer Pfad deklariert werden.

Da ungelayertes CSS laut CSS-Spezifikation Vorrang vor allen @layer-Regeln hat, überschreiben Regeln in zelyra.theme.css automatisch die Framework-Vorgaben:

/* In zelyra.theme.css: Überschreibt Standardstile sauber und konfliktfrei */
.z-table th {
  background: #1a2234;
  color: #ffffff;
}

Alternativ können eigene Regeln explizit im @layer overrides platziert werden:

@layer overrides {
  .z-table th {
    background: #1a2234;
    color: #ffffff;
  }
}

2. Design-Tokens und CSS Custom Properties

Zelyra UI definiert ein durchgängiges System typisierter CSS-Variablen auf dem :root- bzw. html[data-z-ui]-Element.

Farbtokens (Color Tokens)

Token Standardwert (Light) Zweck / Verwendung
--z-color-canvas #f4f6fa Hintergrundfarbe des gesamten Dokuments
--z-color-surface #ffffff Hintergrund von Karten, Formularen und Tabellen
--z-color-surface-raised #ffffff Leicht erhabene Bereiche (z. B. Tabellenköpfe, Dropdowns)
--z-color-text #182230 Primäre Schriftfarbe für Fließtext und Titel
--z-color-text-muted #526174 Abgeschwächte Schrift für Hinweise, Labels, Metadaten
--z-color-border #d8e0e9 Standard-Rahmenfarbe für Tabellen, Inputs und Karten
--z-color-primary #3157a4 Primärfarbe für Buttons, aktive Tabs, Fokusrahmen
--z-color-on-primary #ffffff Kontrast-Textfarbe auf Primärflächen
--z-color-primary-hover #274889 Hover-Zustand für Primärschaltflächen
--z-color-primary-soft #eaf0fb Zarter Hintergrund für Zeilen-Hover und aktive Elemente
--z-color-success #16734c Erfolgsmeldungen, Freigabestatus, bezahlte Rechnungen
--z-color-success-soft #e9f6ef Weicher Hintergrund für Erfolgs-Badges und Notizen
--z-color-warning #795000 Warnungen, Entwürfe, Mahnungen
--z-color-warning-soft #fff4d8 Weicher Hintergrund für Warn-Badges
--z-color-danger #a12e39 Fehler, Stornos, Löschaktionen, Invarianten-Fehler
--z-color-danger-soft #fff0f0 Weicher Hintergrund für Fehlermeldungen
--z-color-focus #275fc5 Farbe des barrierefreien Fokus-Rings (:focus-visible)
--z-color-link #244f9a Textlinks und Zeilenverweise

Maße, Abstände und Radien

:where(html[data-z-ui]) {
  /* Typografie */
  --z-font-sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
  --z-font-mono: ui-monospace, "Cascadia Code", "Segoe UI Mono", monospace;
  --z-font-size: 1rem;
  --z-line-height: 1.5;

  /* Höhen und Inhaltsbreite */
  --z-control-height: 2.75rem; /* Standard-Eingabehöhe */
  --z-content-width: 76rem;    /* Maximale Inhaltsbreite */

  /* Abstände */
  --z-space-1: 0.25rem;  /* 4px */
  --z-space-2: 0.5rem;   /* 8px */
  --z-space-3: 0.75rem;  /* 12px */
  --z-space-4: 1rem;     /* 16px */
  --z-space-5: 1.25rem;  /* 20px */
  --z-space-6: 1.5rem;   /* 24px */
  --z-space-8: 2rem;     /* 32px */

  /* Radien */
  --z-radius-sm: 0.35rem;  /* Inputs, Buttons */
  --z-radius-md: 0.65rem;  /* Karten, Dialoge, Badges */
  --z-radius-lg: 1rem;     /* AppShell-Hauptcontainer */
  --z-radius-pill: 999px;  /* Runde Pill-Badges, Schalter */

  /* Z-Index Ebenen */
  --z-layer-sticky: 10;
  --z-layer-dropdown: 20;
  --z-layer-dialog: 100;
  --z-layer-toast: 120;
}

Kompakte Datendichte (compact)

In administrativen Dashboards, Buchhaltungsprogrammen oder ERP-Modulen wird häufig eine hohe Informationsdichte gewünscht. Zelyra UI unterstützt dies nativ über das HTML-Attribut data-z-density="compact":

<html data-z-ui data-z-density="compact">

Im Compact-Modus reduziert Zelyra UI die Eingabehöhe automatisch von 2.75rem auf 2.25rem und strafft die Innenabstände aller Tabellenzeilen und Formularfelder. Entwickler können die Dichte auch gezielt für einzelne Sektionen (z. B. nur für eine bestimmte Datentabelle) aktivieren:

<div class="z-table-scroll" data-z-density="compact">
  <table class="z-table">...</table>
</div>

3. TableViews formatieren und optimieren

Tabellenansichten (tableview) gehören zu den zentralen Oberflächenelementen von Zelyra. Sie stellen relationale Daten dar, bieten Such-, Filter- und Sortierfunktionen und enthalten Zeilenaktionen.

Die Standard-HTML-Struktur

Ein Zelyra-TableView erzeugt typischerweise folgende HTML-Hierarchie:

<div class="z-generated-page">
  <header class="z-page-header">
    <div class="z-page-header__copy">
      <h1 class="z-page-header__title">Rechnungen</h1>
      <p class="z-page-header__description">Alle erfassten Rechnungen des aktuellen Mandanten.</p>
    </div>
    <div class="z-page-header__actions">
      <a class="z-button z-button--primary" href="/invoices/new">+ Neue Rechnung</a>
    </div>
  </header>

  <form class="zelyra-query-controls" method="get">
    <fieldset>
      <legend>Filter & Suche</legend>
      <div class="z-query-controls__fields">
        <!-- Filterfelder -->
      </div>
    </fieldset>
  </form>

  <div class="z-table-scroll">
    <table class="z-table">
      <thead>
        <tr>
          <th>Nummer</th>
          <th>Kunde</th>
          <th>Datum</th>
          <th>Status</th>
          <th style="text-align: right;">Bruttobetrag</th>
          <th class="z-table__actions-head">Aktionen</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td><strong>RE-2026-0042</strong></td>
          <td>Musterfirma GmbH</td>
          <td>19.10.2026</td>
          <td><span class="z-badge z-badge--success">Bezahlt</span></td>
          <td style="text-align: right;">1.428,00 €</td>
          <td class="z-table__actions">
            <a class="z-button z-button--sm" href="/invoices/42">Anzeigen</a>
            <a class="z-button z-button--sm" href="/invoices/42/edit">Bearbeiten</a>
          </td>
        </tr>
      </tbody>
    </table>
  </div>

  <nav class="z-pagination" aria-label="Seitennavigation">
    <div class="z-pagination__summary">Zeige 1 bis 25 von 148 Einträgen</div>
    <div class="z-pagination__controls">...</div>
  </nav>
</div>

Sticky Header (Fixierter Tabellenkopf)

Wenn Tabellen hunderte Einträge umfassen, scrollt der Tabellenkopf oft aus dem sichtbaren Bereich. Mit Sticky Headers bleibt die Kopfzeile dauerhaft sichtbar:

/* In zelyra.theme.css: Fixierter Tabellenkopf */
.z-table-scroll {
  max-height: 70vh; /* Scrollbarer Bereich mit fester Maximalhöhe */
  overflow-y: auto;
  position: relative;
}

.z-table thead th {
  position: sticky;
  top: 0;
  z-index: var(--z-layer-sticky);
  background: var(--z-color-surface-raised);
  border-bottom: 2px solid var(--z-color-border);
  box-shadow: 0 2px 4px rgb(0 0 0 / 6%);
}

Zebra-Streifen und interaktive Zeilenhervorhebung

Zebra-Streifen verbessern das zeilenweise Erfassen komplexer Zahlenkolonnen dramatisch:

/* Zebra-Streifen für gerade Zeilen */
.z-table tbody tr:nth-child(even) {
  background-color: rgb(0 0 0 / 2%);
}

[data-z-theme="dark"] .z-table tbody tr:nth-child(even) {
  background-color: rgb(255 255 255 / 2.5%);
}

/* Intensiverer Zeilen-Hover */
.z-table tbody tr:hover {
  background-color: var(--z-color-primary-soft);
  transition: background-color var(--z-motion-fast) ease-in-out;
}

Rechtsbündige Zahlen und Währungen (Tabular Nums)

In Tabellen dürfen Zahlen und Beträge niemals linksbündig oder zentriert gesetzt werden, da das menschliche Auge Dezimalstellen untereinander vergleichen muss. Zudem verhindert die Schriftart-Eigenschaft tabular-nums, dass Ziffern wie die schmale 1 das Schriftbild verschieben:

/* Exakte numerische Ausrichtung für Betrags- und Mengenspalten */
.z-table td.col-number,
.z-table td.col-currency,
.z-table th.col-number,
.z-table th.col-currency {
  text-align: right;
  font-variant-numeric: tabular-nums;
  font-feature-settings: "tnum" 1;
}

/* Währungsbeträge dezent hervorheben */
.z-table td.col-currency {
  font-weight: 600;
  letter-spacing: -0.01em;
}

Formatierung der Aktionsspalte (.z-table__actions)

Die Zeilenaktionsleiste bündelt Bearbeiten-, Anzeigen- und Löschschaltflächen:

/* Kompakte, sauber angeordnete Zeilenaktionsknöpfe */
.z-table td.z-table__actions {
  white-space: nowrap;
  text-align: right;
  vertical-align: middle;
}

.z-table td.z-table__actions .z-button,
.z-table td.z-table__actions a.z-button {
  min-height: 1.85rem;
  padding: 0.2rem 0.6rem;
  font-size: 0.82rem;
  font-weight: 500;
  border-radius: var(--z-radius-sm);
}

.z-table td.z-table__actions .z-button:hover {
  transform: translateY(-1px);
}

4. Such-, Filter- und Abfragewerkzeuge

Die Filterleiste über einer TableView wird in Zelyra über .zelyra-query-controls und .z-query-controls__fields gerendert.

/* Modernes, aufgeräumtes Suchleisten-Design */
.zelyra-query-controls {
  border: 1px solid var(--z-color-border);
  border-radius: var(--z-radius-md);
  background: var(--z-color-surface-raised);
  padding: 1rem 1.25rem;
  margin-bottom: 1.5rem;
}

.zelyra-query-controls legend {
  font-size: 0.88rem;
  font-weight: 700;
  color: var(--z-color-text-muted);
  text-transform: uppercase;
  letter-spacing: 0.05em;
  padding: 0 0.4rem;
}

.z-query-controls__fields {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 14rem), 1fr)) auto;
  align-items: end;
  gap: 1rem;
}

/* Eingabefelder in der Filterleiste */
.zelyra-query-controls .z-input,
.zelyra-query-controls .z-select {
  background: var(--z-color-surface);
  border-color: var(--z-color-border);
  box-shadow: inset 0 1px 2px rgb(0 0 0 / 4%);
}

.zelyra-query-controls .z-input:focus,
.zelyra-query-controls .z-select:focus {
  border-color: var(--z-color-primary);
  outline: 3px solid var(--z-color-primary-soft);
}

5. Paginierung und leere Tabellenzustände

Paginierung (.z-pagination)

.z-pagination {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  justify-content: space-between;
  gap: 1rem;
  padding-top: 1.25rem;
  border-top: 1px solid var(--z-color-border);
}

.z-pagination__summary {
  font-size: 0.88rem;
  color: var(--z-color-text-muted);
}

.z-pagination__controls {
  display: inline-flex;
  gap: 0.35rem;
}

.z-pagination__controls a,
.z-pagination__controls span {
  display: inline-flex;
  min-width: 2.25rem;
  height: 2.25rem;
  align-items: center;
  justify-content: center;
  padding: 0 0.5rem;
  border: 1px solid var(--z-color-border);
  border-radius: var(--z-radius-sm);
  background: var(--z-color-surface);
  color: var(--z-color-text);
  font-size: 0.88rem;
  text-decoration: none;
}

.z-pagination__controls a:hover {
  background: var(--z-color-primary-soft);
  border-color: var(--z-color-primary);
}

.z-pagination__controls [aria-current="page"] {
  background: var(--z-color-primary);
  color: var(--z-color-on-primary);
  border-color: var(--z-color-primary);
  font-weight: 700;
}

Leere Zustände (.z-empty-state)

Liefert eine Abfrage keine Ergebnisse, zeigt Zelyra den Zustand .z-empty-state:

.z-empty-state {
  text-align: center;
  padding: 3.5rem 1.5rem;
  background: var(--z-color-surface);
  border: 1px dashed var(--z-color-border);
  border-radius: var(--z-radius-md);
  margin-block: 1rem;
}

.z-empty-state h3 {
  margin: 0 0 0.5rem;
  font-size: 1.2rem;
  color: var(--z-color-text);
}

.z-empty-state p {
  max-width: 30rem;
  margin: 0 auto 1.5rem;
  color: var(--z-color-text-muted);
  font-size: 0.95rem;
  line-height: 1.5;
}

.z-empty-state__actions {
  display: flex;
  justify-content: center;
  gap: 0.75rem;
}

6. CRUD- und Master-Detail-Formulare gestalten

Automatisch generierte Formulare (crud.view.create, crud.view.edit) werden im Container .zelyra-crud-form-card eingebettet.

Zwei-Spalten-Formularlayout mit responsivem Umbruch

/* Card-Hülle des Formulars */
.zelyra-crud-form-card {
  max-width: 68rem;
  margin: 1.5rem auto 3rem;
  padding: 2rem;
  background: var(--z-color-surface);
  border: 1px solid var(--z-color-border);
  border-radius: var(--z-radius-lg);
  box-shadow: var(--z-shadow-sm);
}

/* Zweispaltiges Formular-Grid */
.zelyra-crud-form-card form {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 1fr));
  gap: 1.25rem 1.5rem;
}

/* Vollbreite Felder (z. B. Bemerkungen, Textareas) */
.zelyra-crud-form-card .z-field--full,
.zelyra-crud-form-card .z-fieldset,
.zelyra-crud-form-card .z-form-actions {
  grid-column: 1 / -1;
}

/* Auf mobilen Displays einspaltig umbrechen */
@media (max-width: 768px) {
  .zelyra-crud-form-card form {
    grid-template-columns: 1fr;
  }
}

Formularfelder, Labels und Hilfetexte

.z-field {
  display: grid;
  gap: 0.4rem;
  min-width: 0;
}

.z-field__label {
  font-size: 0.92rem;
  font-weight: 650;
  color: var(--z-color-text);
}

/* Pflichtfeld-Sternchen hervorheben */
.z-field__label[data-required="true"]::after {
  content: " *";
  color: var(--z-color-danger);
}

.z-field__hint {
  font-size: 0.82rem;
  color: var(--z-color-text-muted);
}

.z-input,
.z-select,
.z-textarea {
  min-height: var(--z-control-height);
  padding: 0.55rem 0.8rem;
  border: 1px solid var(--z-color-border);
  border-radius: var(--z-radius-sm);
  background: var(--z-color-surface);
  color: var(--z-color-text);
  transition: border-color var(--z-motion-fast), box-shadow var(--z-motion-fast);
}

.z-input:focus,
.z-select:focus,
.z-textarea:focus {
  border-color: var(--z-color-focus);
  box-shadow: 0 0 0 3px var(--z-color-primary-soft);
  outline: none;
}

Validierungsfehler und Invarianten-Feedback ([aria-invalid="true"])

Meldet die Zelyra-Validierung einen Fehler (z. B. eine verletzte Tabelleninvariante wie total_gross >= total_net), setzt Zelyra das Attribut aria-invalid="true":

/* Roter Signalfokus für fehlerhafte Felder */
.z-input[aria-invalid="true"],
.z-select[aria-invalid="true"],
.z-textarea[aria-invalid="true"] {
  border: 2px solid var(--z-color-danger);
  background-color: var(--z-color-danger-soft);
}

.z-field__error {
  display: flex;
  align-items: center;
  gap: 0.35rem;
  font-size: 0.85rem;
  font-weight: 600;
  color: var(--z-color-danger);
}

/* Gesamtübersicht der Validierungsfehler oben am Formular */
.z-error-summary {
  margin-bottom: 1.5rem;
  padding: 1.25rem;
  border: 1px solid var(--z-color-danger);
  border-left-width: 6px;
  border-radius: var(--z-radius-md);
  background: var(--z-color-danger-soft);
  color: var(--z-color-danger);
}

Master-Detail-Kindtabellen (has_many) und Summenboxen

In Transaktionsformularen mit has_many-Relationen (wie Rechnungspositionen) wird die Kindtabelle nahtlos in das Formular integriert:

/* Kinddatensatz-Tabelle im Formular */
.z-fieldset.z-master-detail-items {
  border: 1px solid var(--z-color-border);
  border-radius: var(--z-radius-md);
  padding: 1.25rem;
  background: var(--z-color-surface-raised);
}

.z-master-detail-items table {
  width: 100%;
  border-collapse: collapse;
}

.z-master-detail-items th,
.z-master-detail-items td {
  padding: 0.6rem 0.5rem;
  border-bottom: 1px solid var(--z-color-border);
}

/* Kompakte Inputs in der Positionstabelle */
.z-master-detail-items input.z-input {
  min-height: 2.15rem;
  padding: 0.25rem 0.5rem;
  font-size: 0.9rem;
}

/* Summenbox für automatische Aggregat-Werte (Netto, MwSt, Brutto) */
.z-form-summary-card {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
  max-width: 22rem;
  margin-left: auto;
  margin-top: 1rem;
  padding: 1.25rem;
  border: 1px solid var(--z-color-border);
  border-radius: var(--z-radius-md);
  background: var(--z-color-surface);
}

.z-form-summary-card__row {
  display: flex;
  justify-content: space-between;
  font-size: 0.95rem;
}

.z-form-summary-card__row--total {
  border-top: 2px solid var(--z-color-border);
  padding-top: 0.65rem;
  margin-top: 0.25rem;
  font-size: 1.15rem;
  font-weight: 750;
  color: var(--z-color-primary);
}

7. Modaldialoge und Status-Badges

Modaldialoge (.z-dialog)

Zelyra verwendet standardkonforme HTML5-<dialog>-Elemente mit nativem Backdrop:

.z-dialog {
  width: min(38rem, calc(100vw - 2rem));
  max-height: min(90vh, 48rem);
  padding: 0;
  border: 1px solid var(--z-color-border);
  border-radius: var(--z-radius-lg);
  background: var(--z-color-surface);
  color: var(--z-color-text);
  box-shadow: var(--z-shadow-md);
  overflow: hidden;
}

/* Dunkel abgedunkelter Hintergrund mit Unschärfe */
.z-dialog::backdrop {
  background: rgb(10 20 35 / 65%);
  backdrop-filter: blur(3px);
}

.z-dialog__header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 1.1rem 1.5rem;
  border-bottom: 1px solid var(--z-color-border);
  background: var(--z-color-surface-raised);
}

.z-dialog__body {
  padding: 1.5rem;
  overflow-y: auto;
}

.z-dialog__footer {
  display: flex;
  justify-content: flex-end;
  gap: 0.75rem;
  padding: 1rem 1.5rem;
  border-top: 1px solid var(--z-color-border);
  background: var(--z-color-surface-raised);
}

Status-Badges (.z-badge)

.z-badge {
  display: inline-flex;
  align-items: center;
  gap: 0.35rem;
  padding: 0.25rem 0.65rem;
  font-size: 0.8rem;
  font-weight: 650;
  line-height: 1;
  border-radius: var(--z-radius-pill);
  border: 1px solid transparent;
  white-space: nowrap;
}

/* Farbvarianten für Beleg- und Buchungszustände */
.z-badge--success {
  background: var(--z-color-success-soft);
  color: var(--z-color-success);
  border-color: rgb(22 115 76 / 20%);
}

.z-badge--warning {
  background: var(--z-color-warning-soft);
  color: var(--z-color-warning);
  border-color: rgb(121 80 0 / 20%);
}

.z-badge--danger {
  background: var(--z-color-danger-soft);
  color: var(--z-color-danger);
  border-color: rgb(161 46 57 / 20%);
}

.z-badge--neutral {
  background: var(--z-color-canvas);
  color: var(--z-color-text-muted);
  border-color: var(--z-color-border);
}

8. Vollständige Praxisrezepte für zelyra.theme.css

Die folgenden Rezepte können direkt in die Datei zelyra.theme.css im Projektverzeichnis übernommen werden.

Rezept 1: Modernes Dark Mode & Accent Theme

Ein sattes, augenschonendes dunkles Theme mit Indigo- und Cyan-Akzenten für Entwicklungs- und Leitstandanwendungen:

/* ==========================================================================
   Rezept 1: Modern Dark Theme für zelyra.theme.css
   ========================================================================== */
:where(html[data-z-ui][data-z-theme="dark"]),
:where(html[data-z-ui]:not([data-z-theme])) {
  /* Tiefes Schieferblau als Basisfarben */
  --z-color-canvas: #0b0f17;
  --z-color-surface: #121824;
  --z-color-surface-raised: #1a2233;
  --z-color-border: #28354b;

  /* Typografie */
  --z-color-text: #f1f5f9;
  --z-color-text-muted: #94a3b8;

  /* Strahlendes Cyan/Indigo als Primärakzent */
  --z-color-primary: #38bdf8;
  --z-color-on-primary: #082f49;
  --z-color-primary-hover: #7dd3fc;
  --z-color-primary-soft: #0c2b45;

  /* Statusfarben */
  --z-color-success: #4ade80;
  --z-color-success-soft: #0e3720;
  --z-color-warning: #facc15;
  --z-color-warning-soft: #3d330c;
  --z-color-danger: #f87171;
  --z-color-danger-soft: #3d1417;

  /* Schatten mit sanftem Schein */
  --z-shadow-sm: 0 1px 3px rgb(0 0 0 / 50%);
  --z-shadow-md: 0 12px 32px rgb(0 0 0 / 70%);
}

/* Akzentuierter Tabellenkopf im Dark Mode */
.z-table thead th {
  background: #172030;
  color: #38bdf8;
  border-bottom: 2px solid #28354b;
}

/* Sanfter Zeilen-Hover */
.z-table tbody tr:hover {
  background-color: #17243b;
}

Rezept 2: Kompakte Finanz- und Buchhaltungstabelle

Optimiert für Buchhaltungslisten, Kassenbücher und Belegübersichten mit fixiertem Tabellenkopf, Währungsausrichtung und schnellem visuellen Scannen:

/* ==========================================================================
   Rezept 2: Finanz- und Buchhaltungstabelle mit Sticky Header
   ========================================================================== */
.z-table-scroll {
  max-height: 72vh;
  overflow: auto;
  border: 1px solid var(--z-color-border);
  border-radius: var(--z-radius-md);
  box-shadow: 0 4px 12px rgb(0 0 0 / 4%);
}

.z-table {
  font-size: 0.9rem;
  border-collapse: separate;
  border-spacing: 0;
}

/* Fixierter Tabellenkopf */
.z-table thead th {
  position: sticky;
  top: 0;
  z-index: 10;
  background: var(--z-color-surface-raised);
  border-bottom: 2px solid var(--z-color-primary);
  padding: 0.65rem 0.75rem;
  font-weight: 700;
  text-transform: uppercase;
  font-size: 0.78rem;
  letter-spacing: 0.04em;
  color: var(--z-color-text);
}

/* Schmale, platzsparende Zeilen */
.z-table td {
  padding: 0.5rem 0.75rem;
  border-bottom: 1px solid var(--z-color-border);
  vertical-align: middle;
}

/* Subtile Streifung */
.z-table tbody tr:nth-child(even) td {
  background-color: rgb(0 0 0 / 1.5%);
}

/* Numerische Spalten rechtsbündig mit fester Ziffernbreite */
.z-table th:nth-child(5),
.z-table td:nth-child(5),
.z-table th:nth-child(6),
.z-table td:nth-child(6) {
  text-align: right;
  font-variant-numeric: tabular-nums;
}

.z-table td:nth-child(5) {
  font-weight: 700;
  color: var(--z-color-text);
}

/* Zeilenaktionen rechtsbündig und kompakt */
.z-table td:last-child {
  text-align: right;
  white-space: nowrap;
}

.z-table td:last-child .z-button {
  min-height: 1.85rem;
  padding: 0.15rem 0.55rem;
  font-size: 0.8rem;
}

Rezept 3: Master-Detail-Rechnungsformular mit Card-Stil

Dieses Rezept gestaltet Belegformulare mit geteilten Kopfdaten, strukturierter Positionstabelle und hervorgehobener Rechnungssummenkarte:

/* ==========================================================================
   Rezept 3: Master-Detail Rechnungsformular mit Card-Design
   ========================================================================== */
.zelyra-crud-form-card {
  max-width: 72rem;
  border: 1px solid var(--z-color-border);
  border-radius: var(--z-radius-lg);
  padding: 2.25rem;
  background: var(--z-color-surface);
  box-shadow: 0 10px 30px rgb(0 0 0 / 5%);
}

/* Headerbereich des Formulars */
.zelyra-crud-form-card > header {
  margin-bottom: 2rem;
  padding-bottom: 1.25rem;
  border-bottom: 1px solid var(--z-color-border);
}

.zelyra-crud-form-card > header h1 {
  font-size: 1.6rem;
  margin: 0 0 0.4rem;
  color: var(--z-color-text);
}

/* Gruppierung der Stammdaten in einer erhabenen Karte */
.z-form-master-section {
  display: grid;
  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: 1.25rem;
  padding: 1.5rem;
  background: var(--z-color-surface-raised);
  border: 1px solid var(--z-color-border);
  border-radius: var(--z-radius-md);
  margin-bottom: 2rem;
}

@media (max-width: 900px) {
  .z-form-master-section {
    grid-template-columns: 1fr;
  }
}

/* Positionstabelle (Kind-Sammlung) */
.z-form-items-table {
  width: 100%;
  border-collapse: collapse;
  margin-block: 1rem 1.5rem;
}

.z-form-items-table th {
  padding: 0.65rem;
  border-bottom: 2px solid var(--z-color-border);
  font-weight: 700;
  font-size: 0.85rem;
  color: var(--z-color-text-muted);
}

.z-form-items-table td {
  padding: 0.5rem;
  border-bottom: 1px solid var(--z-color-border);
}

/* Hervorgehobene Summen-Box rechts unten */
.z-invoice-totals-box {
  display: grid;
  grid-template-columns: 1fr auto;
  gap: 0.6rem 2rem;
  width: min(100%, 24rem);
  margin-left: auto;
  padding: 1.25rem 1.5rem;
  background: var(--z-color-surface-raised);
  border: 1px solid var(--z-color-border);
  border-radius: var(--z-radius-md);
}

.z-invoice-totals-box dt {
  color: var(--z-color-text-muted);
  font-size: 0.95rem;
}

.z-invoice-totals-box dd {
  margin: 0;
  font-weight: 650;
  font-variant-numeric: tabular-nums;
  text-align: right;
}

.z-invoice-totals-box dt.total-gross,
.z-invoice-totals-box dd.total-gross {
  border-top: 2px solid var(--z-color-border);
  padding-top: 0.75rem;
  margin-top: 0.25rem;
  font-size: 1.25rem;
  font-weight: 800;
  color: var(--z-color-primary);
}

/* Formular-Aktionsleiste */
.z-form-actions {
  display: flex;
  justify-content: flex-end;
  gap: 1rem;
  margin-top: 2.5rem;
  padding-top: 1.5rem;
  border-top: 1px solid var(--z-color-border);
}

.z-form-actions .z-button--primary {
  min-width: 11rem;
  font-size: 1rem;
}

37. Native Datenbank-CLI und interaktive Sprachkonsole

Mit Zelyra 1.2.25 und 1.2.26 wurde die Entwickler- und Administrationserfahrung um eine direkte Datenbank-CLI sowie eine interaktive AST-Sprachkonsole erweitert.

Direkte Datenbankkonsole (zelyra db console)

Der Befehl zelyra db console [main.zyl] liest die Konfiguration der Ziel-Datenbank aus Umgebungsvariablen (ZELYRA_DATABASE_<NAME>_URL bzw. DATABASE_URL) sowie der Projekt-.env aus und startet direkt den passenden nativen Client (MariaDB/MySQL mysql oder PostgreSQL psql). Passwörter werden sicher über Umgebungsvariablen (MYSQL_PWD bzw. PGPASSWORD) übergeben, sodass sie weder in der Prozessliste noch in Logs sichtbar sind:

# Startet den nativen Datenbank-Client mit der konfigurierten Projekt-Verbindung
zelyra db console main.zyl

Direkte Abfragen über die CLI (zelyra db query)

Der Befehl zelyra db query führt eine einzelne SQL-Anweisung transaktional aus. Zur Absicherung gegen versehentliche Modifikationen laufen Abfragen standardmäßig in einer von der Datenbank erzwungenen schreibgeschützten Transaktion:

# Standardmäßig schreibgeschützte Abfrage mit tabellarischer Formatierung
zelyra db query main.zyl "SELECT id, email, created_at FROM customers" --format table

# JSON- oder CSV-Format für Skripte und Pipeline-Verarbeitung
zelyra db query main.zyl "SELECT id, email FROM customers" --format json
zelyra db query main.zyl "SELECT id, email FROM customers" --format csv

# Schreibende DML-Operationen erfordern das explizite Flag --allow-mutation
zelyra db query main.zyl "UPDATE customers SET active = true WHERE id = 1" --allow-mutation

# Begrenzung und Mandantenbindung über Platzhalter :tenant_id
zelyra db query main.zyl "SELECT * FROM invoices WHERE tenant_id = :tenant_id" --tenant 42 --limit 50

[!NOTE] DDL-Anweisungen (ALTER, DROP, CREATE) sind in zelyra db query bewusst blockiert, da viele Datenbank-Engines DDL implizit committen und damit Transaktionssicherheitsnetze aushebeln.

Interaktive Sprachkonsole (zelyra console)

Die mit Zelyra 1.2.26 eingeführte Sprachkonsole startet eine interaktive Read-Eval-Print-Loop (REPL) auf Basis des AST-Interpreters:

zelyra console main.zyl

Merkmale der Sprachkonsole:

38. Laravel-Importanalyse und Migrationsgrundlage

Zelyra 1.2.27 stellt ein spezialisiertes CLI-Werkzeug bereit, um vorhandene Laravel-Projekte quellbelegt zu analysieren und als native, typgeprüfte Zelyra-Module zu rekonstruieren.

Read-Only-Analyse

Der Importer arbeitet nach dem Prinzip Read-Only First. Er führt zu keinem Zeitpunkt unvertrauenswürdigen PHP-Code aus, sondern analysiert syntaktisch und semantisch:

  1. Migrationen und Schema-Definitionen
  2. Eloquent-Models, Beziehungen und Casts
  3. Validierungsregeln aus Request-Klassen und Controllern
  4. Blade-Templates und Asset-Referenzen
# Reine Strukturanalyse ohne Schreibvorgänge
zelyra import laravel analyze /pfad/zum/laravel-projekt

Selektive Codegenerierung

Die Generierung nativer Zelyra-Artefakte erfolgt gezielt und isoliert:

# Generiert native Zelyra-Tabellen und -Records für eine bestimmte Tabelle
zelyra import laravel generate /pfad/zum/laravel-projekt --table customers

# Generiert alle unterstützten Kernmodule
zelyra import laravel generate /pfad/zum/laravel-projekt --all-supported

Dabei werden folgende Transformationen vorgenommen:

39. Typisierte transaktionale CRUD-Actions

Mit Version 1.2.28 führt Zelyra typisierte CRUD-Actions ein. Sie erlauben es, fachliche Aktionen direkt an Tabellen- und Datensatzkontexte zu binden, ohne CRUD-Sicherheitsgrenzen aufzugeben.

Deklaration von Actions

Eine Action bindet typisierte Parameter, den aktuellen gesperrten Datensatz (row) sowie vertrauenswürdige Sitzungsinformationen (session):

table Invoices scoped by tenant_id: TenantId {
  id: Id required,
  tenant_id: TenantId required,
  number: String(50) required unique within tenant,
  status: String(20) required default "draft",
  total_gross: Decimal(12, 2) required default 0.00,
  locked: Bool required default false,

  action approve(comment: String(200)?) {
    guard row.status == "draft" {
      error: "Nur Entwürfe können genehmigt werden."
    }
    guard row.locked == false {
      error: "Gesperrte Belege können nicht genehmigt werden."
    }

    requires {
      comment != ""
    }

    execute {
      UPDATE Invoices
      SET status = "approved",
          approved_by = session.user_id,
          approved_at = now()
      WHERE id = row.id AND tenant_id = session.tenant_id;

      // Automatisches Einreihen in Audit-Log und PDF-Outbox in derselben Transaktion
      enqueue_audit_log("invoice.approved", row.id);
    }
  }
}

Transaktionale Garantien von Actions

40. Sichere Datei-Uploads und Mandanten-Dateispeicher

Zelyra 1.2.29 führt sichere, begrenzte Multipart-Datei-Uploads ein. Sie verbinden compilergeprüfte Formularfelder mit privatem, mandantenisoliertem Dateispeicher.

Deklaration von Datei-Feldern

Upload-Felder werden mit strengen Typ-, Größen- und Formatgrenzen deklariert:

table Documents scoped by tenant_id: TenantId {
  id: Id required,
  tenant_id: TenantId required,
  title: String(100) required,
  attachment: File(
    max_size: 10_000_000, // 10 MB Limit
    allowed_types: ["application/pdf", "image/png", "image/jpeg"]
  ) required,
  uploaded_at: DateTime required default now()
}

Sicherheitsarchitektur

  1. Signaturprüfung: Dateiinhalte werden nicht allein anhand der Dateiendung oder des vom Client übergebenen MIME-Typs beurteilt, sondern durch serverseitige Magic-Byte-Signaturprüfung (PDF-, PNG- und JPEG-Signaturen).
  2. Privater Speicher außerhalb des Web-Roots: Hochgeladene Dateien werden unter opaken SHA-256-Hash-Token (FileRef) in einem geschützten, mandanteneigenen Verzeichnis abgelegt. Ein direkter Zugriff über den Webserver ohne Authentifizierung ist technisch unmöglich.
  3. Geschützte Downloads: Der Zugriff auf Dateien erfolgt über autorisierte CRUD-Routen, die vor Auslieferung den Mandantenkontext und die Benutzerberechtigungen prüfen.
  4. Lebenszyklus und Waisenbereinigung:
    • Wird eine Datei in einem Datensatz ersetzt, wird die alte Datei erst nach erfolgreichem Commit der Datenbanktransaktion gelöscht.
    • Beim Löschen eines Datensatzes wird die physische Datei nur gelöscht, wenn keine andere FileRef-Referenz mehr darauf verweist.
    • zelyra files cleanup spürt verwaiste Uploads auf. Der Befehl arbeitet standardmäßig als vorschauende Trockenübung und erfordert zur Ausführung --apply --maintenance-window.
  5. Prüfsummen-Backup: 
    # Erstellt ein prüfsummenvalidiertes Backup des Dateispeichers
zelyra files backup /var/backups/zelyra-files.tar.gz

# Stellt den Dateispeicher wieder her und validiert alle Prüfsummen
zelyra files restore /var/backups/zelyra-files.tar.gz

41. Mandanten-Nummernkreise und Sequenzen (auto_sequence)

Mit Zelyra 1.2.31 wurden deklarierte, mandantensichere Nummernkreise für String-Felder in Tabellen und generierten CRUD-Ressourcen eingeführt.

Deklaration von Nummernkreisen

Ein Nummernkreis wird mit auto_sequence("FORMAT") direkt an einer Spaltendeklaration definiert:

table customers scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    customer_number: String(32) required unique within tenant auto_sequence("KD-{0001}")
    name: String(100) required
}

table quotes scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    quote_number: String(40) required unique within tenant auto_sequence("AG-{year}-{0001}")
    total: Decimal(12, 2) required default 0.00
}

Formatbausteine:

Interne Verwaltung und Datenbankgarantien

  1. Verwaltete Sequenztabelle: Der Schema-Planer erzeugt automatisch die interne Tabelle _zelyra_number_sequences, die den Zählerstand speichert.
  2. Atomare Transaktion: Die Zählererhöhung und das Einfügen des neuen Datensatzes erfolgen in derselben Datenbanktransaktion.
  3. Schutz vor Manipulation: In generierten CRUD-Formularen und APIs werden vom Client übermittelte Nummernwerte ignoriert. In Bearbeitungsformularen wird die generierte Nummer schreibgeschützt dargestellt.
  4. Keine Lückenlosigkeit: Zelyra garantiert strikte Eindeutigkeit und Monotonie pro Mandant, verspricht jedoch bewusst keine lückenlose Zählung. Bei Transaktions-Rollbacks wird eine vergebene Nummer nicht erneut vergeben, um Nachvollziehbarkeit und GoBD-Konformität zu wahren.
  5. Backend-Unterstützung: MariaDB und PostgreSQL werden vollständig unterstützt. SQLite wird bei der Schemaprüfung mit error[E-DB-001] abgewiesen.

42. Typisierte berechnete Geschäftsfelder (compute) und FileRef-Anhänge im CRUD

Zelyra 1.2.32 führt zwei wesentliche Funktionen für geschäftliche Kernabläufe ein: typisierte, serverseitig berechnete Felder und schemagebundene FileRef-Anhänge in generierten CRUD-Ansichten.

Typisierte berechnete Felder (compute)

Felder mit compute(expr) berechnen ihren Wert deterministisch aus anderen Spalten desselben Datensatzes:

table invoice_items {
    id: Id primary auto
    invoice_id: Id required references invoices
    quantity: Decimal(10, 2) required
    unit_price: Decimal(12, 2) required
    total: Decimal(12, 2) required compute(quantity * unit_price)
}

Eigenschaften und Compiler-Prüfungen:

FileRef-Anhänge im generierten CRUD

Spalten vom Typ FileRef können über einen deklarierten attachment-Block direkt an generierte CRUD-Formulare angebunden werden:

table contracts scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    title: String(200) required
    signed_pdf: FileRef? attachment {
        max_size: "20MB"
        allowed_types: ["application/pdf"]
    }
}

crud Contract -> contracts {}

43. Multi-Backend-Parität, Transaktions-Rollback und PDF-Outbox

Zelyra 1.2.33 konzentriert sich auf die semantische Ausrichtung zwischen dem AST-Referenzinterpreter, der Typed-MIR-Pipeline und der Bytecode-VM (v24).

Ausrichtung des Schrittbudgets (--max-steps)

Das konfigurierbare Ausführungsbudget --max-steps N wird über AST, MIR und Bytecode-VM hinweg auf Basis derselben Quellspannen und Ausdrucksknoten abgerechnet. Endlosschleifen oder rechenintensive Operationen werden in allen Backends nach exakt derselben Schrittanzahl deterministisch abgebrochen.

Transaktionale PDF-Mail-Outbox

Das Zusammenspiel von serverseitigem PDF-Rendering (render_pdf) und E-Mail-Einreihung (mail_queue) ist vollständig transaktional abgesichert:

fn send_invoice(recipient: String, invoice: Invoice) uses Email, Database(write) {
    transaction {
        mail_queue(
            recipient,
            "Rechnung " + invoice.number,
            "Ihre Rechnung " + invoice.number + " ist beigefügt.",
            "invoice-" + invoice.number + ".pdf",
            render_pdf("InvoicePrint", invoice)
        )
    }
}
  1. Atomarität: Schlägt die umgebende Transaktion fehl (z. B. durch einen Datenbankfehler oder Invariantenverletzung), werden weder die PDF-Datei noch der E-Mail-Versandauftrag in der Outbox persistiert.
  2. Backend-Gleichheit: Differentialtests stellen sicher, dass AST, MIR und Bytecode-VM bei Transaktionsfehlern dieselben Fehlerdiagnosen liefern und den Rollback zuverlässig durchführen.

ANHÄNGE

Anhang A: Schnelleinstieg / Spickzettel (Syntax-Cheat-Sheet)

Grundlegende Syntax

# Kommentar gilt bis zum Zeilenende. Für einen Block stehen öffnendes und schließendes ## jeweils allein auf einer Zeile; dazwischen steht der Kommentartext.

# Funktionen mit Vertraegen
fn summe(a: Int, b: Int) -> Int
    requires { a >= 0 && b >= 0 }
    ensures { result >= 0 }
{
    return a + b
}

# Einstiegspunkt und Variablen
fn main() {
    x = 10                  # Typableitung (unveraenderlich)
    mutable zaehler = 0     # Veraenderlich
    name: String = "Zelyra" # Expliziter Typ

    print(summe(3, 7))
}

Typen

Kontrollstrukturen

fn kontrolle(x: Int) {
    if x > 10 {
        print("Gross")
    } else {
        print("Klein")
    }

    match x {
        1 => { print("Eins") }
        2 => { print("Zwei") }
        _ => { print("Andere") }
    }

    mutable i = 0
    while i < 3 invariant { i >= 0 } {
        i = i + 1
    }

    for n in [1, 2, 3] {
        print(n)
    }
}

fn main() {
    kontrolle(1)
}

Datenbank & Web

database main {
    engine: mariadb
    database: "app"
}

table items {
    id: Id primary auto
    bezeichnung: String required
}

page "/items" {
    html {
        <h1>Artikelliste</h1>
    }
}

Anhang B: Alle Fehlermeldungen von Zelyra auf einen Blick

Fehlercode Kategorie Beschreibung Typische Behebung
E-LEX-001 Lexer Unerwartetes Zeichen / Lexikalischer Fehler Tippfehler oder unzulässiges Sonderzeichen entfernen
E-PARSE-001 Parser Syntaxfehler (z. B. fehlende Klammer, falsches Token) Syntax gemäß Zelyra-Grammatik korrigieren
E-NAME-001 Auflösung Unbekannter Name / Variable nicht gefunden Deklaration prüfen oder Tippfehler korrigieren
E-TYPE-001 Typprüfung Typkonflikt (z. B. String zugewiesen an Int) Typen anpassen oder Konvertierung vornehmen
E-FEATURE-001 Feature-Schalter Zugriff auf eine deaktivierte Sprachoberfläche (web, api, crud, auth, audit) Feature in zelyra.toml oder .env aktivieren
E-CAP-001 / E-CAP-002 Capabilities Fehlende Capability-Berechtigung (z. B. database, network) In zelyra.toml unter [capabilities] freigeben
E-POLICY-001 / 002 Richtlinien Verstoß gegen Sicherheits- oder Audit-Richtlinien Sicherheitsdeklaration prüfen
E-DB-001 - E-DB-005 Datenbank Datenbankverbindungs- oder Treiberfehler DATABASE_URL prüfen, MariaDB-Dienst starten
E-SQL-001 - E-SQL-004 SQL Ungültiges SQL / Schema-Misfit / Spalte nicht existent SQL-Anweisung gegen Tabellendefinition prüfen
E-VIEW-001 - E-VIEW-009 Views & Pages Fehler in View-Interpolation, Slots oder Datenbindung Slot-Namen und Datentypen der Page-Bindung prüfen
E-VIEW-010 - E-VIEW-015 Query-Controls Ungültige Such-, Sortier-, Paginierungs- oder Filterfelder Deklarierte Whitelist (search, sort, filter) prüfen
E-FORM-001 - E-FORM-004 Formulare Validierungsfehler oder ungültige Feldtypen Formular-Deklaration und Eingabedaten anpassen
E-CRUD-001 - E-CRUD-006 CRUD Ungültige CRUD-Ressource, Schema-Konflikt oder Layout-Fehler Tabellenverknüpfung und Layout-Slots prüfen
E-AUTH-001 - E-AUTH-028 Authentifizierung Session-, Passwort- oder Berechtigungskonflikt Rollen (permits), requires auth und Hashes prüfen
E-AUDIT-001 - E-AUDIT-010 Audit-Trail Fehler in der kryptografischen Hash-Kette des Audit-Logs Prüfsummen und Audit-Tabelle validieren
E-SETUP-001 - E-SETUP-006 Setup-Flow Portkonflikt, Socket-Fehler oder Compose-Problem Freie Ports wählen, Docker-Berechtigungen prüfen
E-SETUP-WEB-001 Web-Setup Ungültiges oder abgelaufenes Setup-Token Setup-Assistenten neu starten und Token-URL nutzen
E-IMPACT-001 Impact-Analyse Zyklische oder ungültige Abhängigkeiten Quellcode-Abhängigkeiten entflechten
E-RUNTIME-001 Laufzeit Unbehandelter Laufzeitfehler Verträge (requires, ensures) oder Fehlerwerte prüfen

Anhang C: Zelyra-CLI-Referenz

Befehl Option / Flag Beschreibung
zelyra --version Gibt den vollständigen Compiler- und Paketversionsstand aus
zelyra new <dir> --template minimal|mariadb-crud|... Erstellt ein neues Zelyra-Projekt mit Vorlage
--mariadb Erzeugt MariaDB-Projekt mit Compose, Dockerfile und .env
--web-port <p> --host-port <p> --db-host-port <p> Konfiguriert Container- und Host-Ports
zelyra init [--mariadb] Initialisiert das aktuelle Verzeichnis als Zelyra-Projekt
zelyra check <file.zyl> [--format json] Prüft Syntax, Typen, Verträge und Capabilities statisch
zelyra run <file.zyl> Kompiliert und führt ein Zelyra-Programm aus
zelyra serve <file.zyl> [host:port] Startet den integrierten HTTP-Webserver
zelyra routes <entry.zyl> [--format human|json] Listet erkannte Routen mit HTTP-Methode und Quellfundstelle; Kollisionen derselben Methode melden E-ROUTE-001
zelyra setup [--database] Startet Docker Compose
[--schema] Startet Umgebung und wendet Datenbankschema an
[--all] Führt Konfiguration, Start und Migration in einem Schritt aus
[--host-port <p>] [--db-host-port <p>] Setzt verbindliche Host-Ports für die neue .env
zelyra setup --web [--port <p>] Startet den lokalen, token-geschützten Browser-Setup-Assistenten
zelyra config <file.zyl> [--format json] Zeigt die wirksame Konfiguration und Feature-Schalter geheimnisfrei an
zelyra doctor <file.zyl> [--port <p>] [--json] Prüft Toolchain, MariaDB, Docker und Ports ohne DB-Änderung
[--env-file <file>] Liest gezielt DATABASE_URL aus der angegebenen Datei
zelyra fmt <file.zyl> [--check] Formatiert Quellcode nach dem offiziellen Standard
zelyra verify <file.zyl> Führt formale Vertragsverifikation durch
zelyra doc <file.zyl> --openapi Generiert OpenAPI-3.0-Spezifikationen
--typescript Generiert typisierten, abhängigkeitsfreien TypeScript-Client
zelyra db create <file.zyl> Erzeugt SQL für die Datenbankeinrichtung
zelyra db setup <file.zyl> Richtet die MariaDB-Datenbank initial ein
zelyra db map <file.zyl> [--format=text|json] Vergleicht schreibgeschützt deklarierte Tabellen mit Live-Tabellen, Spalten und Fremdschlüsseln
zelyra db plan <file.zyl> Zeigt die geplanten Schemaänderungen; prüfe den Plan vor der Migration
zelyra db apply <file.zyl> Wendet Schema-Migrationen sicher an
zelyra auth hash-password [--stdin] Erzeugt sichere Argon2-Passworthashes
zelyra form validate <file> <Form> Prüft Formulare mit Testwerten auf der Konsole
zelyra context <file.zyl> [--format json] Gibt den semantischen Quellcode-Kontext für Tools aus
zelyra editor [directory] [--port <p>] [--no-open] Startet Studio
zelyra --tutorial invoice [directory] [--no-start] Erzeugt das Rechnungstutorial
zelyra outbox setup <file.zyl> Richtet die MariaDB-Outbox ein
zelyra outbox list <file.zyl> [--limit <1..200>] [--format text|json] Zeigt Einträge
zelyra outbox run <file.zyl> --handler <event.type=function> [--once] Verarbeitet fällige Ereignisse
zelyra outbox requeue <event-id> <file.zyl> Reiht erneut ein
`zelyra task <list run> <file.zyl>` [command] [options]
`zelyra service <install status restart
`zelyra schedule <list export> <file.zyl>` [--format cron|json]
zelyra module init <dir> --name <n> [--version <semver>] Erstellt ein offline nutzbares lokales Zelyra-Modulpaket
zelyra module list <file.zyl> [--format human|json] Zeigt Quellmodule, Exporte, Prüfsummen und Einstellungs-Schemas
zelyra module settings check <file.zyl> [--format json] Validiert typisierte Moduleinstellungen und Geheimnisse
zelyra module plan <entry.zyl> <target> Ermittelt den statischen Modulabschluss und Abhängigkeitsgraphen
zelyra module bundle <entry> <target> --output <dir> [--docker] Schnürt ein portables Quellbundle mit isolierten Paketabhängigkeiten
zelyra package lock [file.zyl] [--check|--update] Prüft oder aktualisiert die SHA-256-Integrität in zelyra.lock
zelyra package keygen|sign|verify [options] Erstellt Ed25519-Schlüssel und signiert/prüft Quellarchive (.zpkg)
zelyra package trust <add|list|remove> [publisher] [key-hex] Verwaltet autorisierte Herausgeberschlüssel in zelyra.trust.toml
zelyra package registry build <dir> Erzeugt einen statischen Index (index.json) aus .zpkg-Dateien
zelyra package search <url> [filter] Durchsucht einen statischen Paketindex nach Namen
zelyra package add <url> <pkg> <ver> --as <alias> Installiert eine exakte, vertrauensgeprüfte Paketversion
zelyra package update <url> <pkg> <ver> --as <alias> [--plan <file>] Aktualisiert Paketabhängigkeiten deterministisch
zelyra package remove <alias> Entfernt eine Paketabhängigkeit und aktualisiert das Lockfile
zelyra package cache clean [--apply] Prüft und bereinigt unreferenzierte Cache-Versionen sicher
zelyra package recover [--apply] Stellt nach abgebrochenen Transaktionen Manifest und Lock wieder her
zelyra reflect <entry.zyl> [--format=json|human] Exportiert Symbole, Schemata, Routen und Contracts als JSON
zelyra audit <inspect|export|verify|prune> <file.zyl> [options] Prüft, verifiziert oder bereinigt Audit-Logs der Anwendung
zelyra migrate-layout --check [entry.zyl] [--format human|json] Prüft die Konformität mit dem kanonischen Standard-Layout
zelyra db history <file.zyl> Zeigt die angewendete Schema-Migrationshistorie
zelyra update [--check] Prüft oder installiert das stabile Release

Anhang D: Die Standardbibliothek im Überblick (Zelyra 1.0.3 bis 1.0.7)

Die eingebaute Zelyra-Standardbibliothek umfasst Funktionen für Mathematik, Textverarbeitung, Sammlungsoperationen, Mengen, Maps, Datumsrechnung, Fehlerkontrolle, Web-Sicherheit, Encodings, Pfade sowie PDF-Rendering. Pipeline-Stufen werden typgeprüft und unterstützen seit 1.0.7 lexikalische Lambdas. Funktionen, die auf externe Systemressourcen zugreifen (z. B. Zufall, Dateisystem, Uhrzeit, E-Mail), erfordern wie gewohnt die entsprechende Capability.

1. Mathematik & Numerik (ohne Capabilities)

2. Strings & Textverarbeitung

3. Arrays & Sammlungen

4. Mengen (Sets)

5. Maps & Wörterbücher

6. Datums- & Kalenderberechnung

7. Ablauf-, Option- und Result-Kontrolle

8. Typkonvertierung & Parsing

9. Sicherheit, Hashing & Web-Encodings

10. Pfade & Dateisystem

11. Capability-geschützte System-APIs

Anhang E: SQL-Spickzettel für Zelyra-Entwickler

In Zelyra eingebettetes SQL wird mit sql<T[]> oder sql ausgeführt:

database main {
    engine: mariadb
    database: "app"
}

table tasks {
    id: Id primary auto
    name: String required
    erledigt: Bool default false
}

fn sql_beispiele() uses Database {
    # 1. SELECT mit typisiertem Rueckgabetyp und sicherem Parameter
    status = false
    gefiltert = sql<Task[]> {
        SELECT id, name, erledigt
        FROM tasks
        WHERE erledigt = :status
    }

    # 2. INSERT in einer Transaktion
    text = "Neue Aufgabe"
    transaction {
        sql {
            INSERT INTO tasks (name, erledigt)
            VALUES (:text, false)
        }
    }

    # 3. UPDATE
    ziel_id = 1
    transaction {
        sql {
            UPDATE tasks
            SET erledigt = true
            WHERE id = :ziel_id
        }
    }
}

fn main() uses Database {
    print("SQL Spickzettel validiert.")
}

Anhang F: HTML- und Web-Referenz in Zelyra

Web-Strukturen und Deklarationen

Element Deklaration Zweck
Page page "/pfad/{param}" { ... } Definiert eine HTTP-GET-Route mit Pfadparametern und HTML-Antwort
View-Layout view LayoutName { html { ... <slot /> ... } } Wiederverwendbares Layout mit Standard- und benannten Slots
Component component Name { props { ... } html { ... } } Wiederverwendbare HTML-Komponente mit typisierten Eigenschaften
Named Slot <slot name="header">Fallback</slot> Platzhalter im Layout/Komponente mit optionalem Standardinhalt
Slot Injection <slot name="header">Inhalt</slot> Übergabe von Kindinhalten an den passenden Slot
Data Loading load item = sql<Item> { SELECT ... } Typisiertes Laden eines Einzeldatensatzes mit Feldzugriff {item.field}
Collection Loop for item in items { <li>{item.name}</li> } Typisierte serverseitige Iteration über geladene Datensätze
Search Control search { col1 col2 } Whitelist-geprüfte URL-Suche mit parametrisierter LIKE-Abfrage
Sort Control sort { col1 col2 } Typisierte Sortierung über ?sort=col&order=asc|desc
Pagination paginated 25 Paginierung mit LIMIT/OFFSET, page, pages und total
Filter Control filter { col1 col2 } Typisierte Filteroperatoren (eq, contains, starts_with, gt, lte etc.)
CRUD Layout crud Res { table tbl layout: LayoutName } Bindet generierte CRUD-Ansichten in Slots title, nav, content, actions ein

Zelyra UI: Designsystem & CSS-Architektur (ab Version 1.0.6)

Ab Zelyra 1.0.6 enthält die Plattform ein vollwertiges, compilergeprüftes UI- und CSS-Framework für datenbankgestützte Geschäftsanwendungen. Es ersetzt unübersichtliche externe Abhängigkeiten durch ein lokal gebündeltes Designsystem (zelyra-ui.v1.css).

CSS-Architektur mit Standard @layer

Das Stylesheet ist hierarchisch in sieben standardkonforme CSS-Schichten strukturiert:

@layer reset, base, theme, layout, components, utilities, overrides;
  1. reset: Normalisierung moderner HTML5-Elemente ohne aggressive Resets.
  2. base: Typografie, Standard-Zeilenabstände und semantische Standardelemente.
  3. theme: Design Tokens und Farbsysteme (light, dark, system) über CSS Custom Properties.
  4. layout: App-Shells (.z-app-shell), Header, responsive Raster und Navigation.
  5. components: 55 wiederverwendbare Komponenten (Cards, Buttons, Inputs, Badges, Tabs, Alerts, Modals, Tables, Charts).
  6. utilities: Präzise Hilfsklassen für Abstände, Ausrichtungen und Textfluss.
  7. overrides: Sichere projektlokale Anpassungen (aus zelyra.theme.css).

Design Tokens & CSS Custom Properties

Token Standardwert (Light) Dunkelwert (Dark) Verwendung
--z-color-primary #2f54eb #a8bfff Primäraktionen, Links, Fokus-Rahmen
--z-color-surface #ffffff #1b232d Karten- und Container-Hintergrund
--z-color-canvas #f4f6f9 #141a22 Gesamter Seitenhintergrund
--z-color-text #1f2937 #edf2f8 Haupttext
--z-color-border #d9dfe7 #3a4655 Trennlinien und Rahmen
--z-color-success #10b981 #8dd6ad Erfolgsmeldungen und Validierungs-Feedback
--z-color-warning #f59e0b #f0ca75 Warnhinweise und Fälligkeitswarnungen
--z-color-danger #ef4444 #ffafb2 Fehlerzustände und Löschaktionen

Themes, Dichte und Barrierefreiheit

Die Steuerung erfolgt über semantische Root-Attribute am <html>- oder Shell-Tag:

55 Typisierte Komponenten (zelyra/ui)

Das Modul zelyra/ui stellt typisierte Standardkomponenten für Geschäftsoberflächen bereit:

Druck- und Dokumenten-Styling (@media print)

Für Rechnungen, Lieferscheine und Audit-Berichte enthält Zelyra UI optimierte Druckregeln:

Stylesheet-Treiber (ZELYRA_UI_STYLESHEET)

Über die Umgebungskonfiguration lässt sich das Stylesheet-Verhalten steuern:

Anhang G: Glossar der Fachbegriffe

Die Einträge verweisen auf das Kapitel, in dem der Begriff erläutert wird. Nicht unterstützte Sprachkonstrukte und CLI-Befehle sind als solche gekennzeichnet.

Anhang H: Lösungen zu den Übungsaufgaben der Kapitel

Willkommen in der vollständigen Lösungsmöglichkeitsübersicht! Hier findest du zu jedem der 43 Kapitel des Lehrbuchs didaktisch aufbereitete, praxiserprobte und syntaktisch verifizierte Lösungsvorschläge für alle Übungsaufgaben (Stufe 1 bis 3).

[!TIP] Der Ehrenkodex für Entwickler: Wirf erst dann einen Blick in diese Lösungen, wenn du mindestens eine frische Tasse Kaffee lang selbst getüftelt, deinen Code mit zelyra check herausgefordert und vielleicht die eine oder andere freundliche Belehrung des Compilers eingesteckt hast. Das echte Programmierer-Glücksgefühl stellt sich erst ein, wenn der Compiler nach eigener Denkarbeit endlich lautlos nickt!

Kapitel 1: Willkommen bei Zelyra

fn main() {
    vorname = "Stefan"
    wohnort = "Berlin"
    print("Hallo Welt! Ich bin " + vorname + " aus " + wohnort + " und programmiere mit Zelyra.")
}

fn begruessen(name: String) -> String {
    return "Guten Tag, " + name + "! Bereit fuer saubere Typen und null Bugs?"
}

fn verabschieden(name: String) -> String {
    return "Auf Wiedersehen, " + name + "! Moegen deine Builds immer gruen bleiben."
}

fn main() {
    benutzer = "Alex"
    print(begruessen(benutzer))
    print(verabschieden(benutzer))
}
  1. Vertauschen von Typen (Text statt Zahl) führt zu Rechenfehlern.
  2. Unbemerktes Weiterreichen von null stürzt erst 20 Zeilen später in fremden Modulen ab.
  3. Falsch geschriebene Eigenschaftsnamen (user.emial) werden stillschweigend ignoriert und liefern undefined. Zelyras Compiler prüft diese Beziehungen vor der Ausführung und garantiert, dass Typen, Feldnamen und Signaturen exakt zusammenpassen.

Kapitel 2: Wie ein Programm funktioniert

  1. Einstiegspunkt: main() wird vom Betriebssystem aufgerufen.
  2. Variablen-Initialisierung: aktueller_tag und ziel_tag werden unveränderlich an Werte gebunden.
  3. Funktionsaufruf: tage_bis_ziel(...) wird mit diesen Argumenten aufgerufen; der Ausführungskontext wechselt in die Funktion.
  4. Rückgabe: Der berechnete Wert wird an main() zurückgegeben und via print() auf der Standardausgabe ausgegeben.
fn tage_bis_ziel(aktueller_tag: Int, ziel_tag: Int) -> Int {
    if aktueller_tag > ziel_tag {
        return 0
    }
    return ziel_tag - aktueller_tag
}

fn main() {
    print(tage_bis_ziel(10, 25)) # Ausgabe: 15
    print(tage_bis_ziel(30, 25)) # Ausgabe: 0 (Frist bereits abgelaufen)
}

Kapitel 3: Zelyra installieren und einrichten

zelyra doctor
zelyra --version

Erklärung: zelyra doctor analysiert die Laufzeitumgebung, prüft die Verfügbarkeit von MariaDB/Docker Compose v2 und zeigt die installierte Release-Version an.

zelyra check --help
zelyra check main.zyl --format json

Erklärung: Mit --format json liefert der Compiler maschinenlesbare Fehlermeldungen mit exakten Spalten-, Zeilen- und Fehlercodes, ideal für CI/CD-Pipelines oder IDE-Erweiterungen.

{
  "files.associations": {
    "*.zyl": "zelyra"
  }
}

Zusammen mit der im Downloadbereich verfügbaren Syntaxerweiterung (zelyra.vsix) erhältst du sofort Syntax-Highlighting und Einrückungsregeln.

Kapitel 4: Das erste Zelyra-Projekt

zelyra new mein_erstes_projekt
cd mein_erstes_projekt
zelyra run main.zyl

[project]
name = "mein_erstes_projekt"
version = "0.3.0"
authors = ["Stefan Siedelmann"]

In main.zyl:

fn main() {
    app_titel = "Aufgaben-Zentrale"
    app_version = "0.3.0"
    print(app_titel + " v" + app_version + " erfolgreich gestartet.")
}

zelyra fmt main.zyl
zelyra fmt --check main.zyl

Erklärung: zelyra fmt vereinheitlicht Einrückungen und Leerzeichen deterministisch. --check liefert den Exit-Code 0, wenn der Code bereits perfekt formatiert ist.

Kapitel 5: Werte und Datentypen

fn main() {
    titel: String = "Inception"
    erscheinungsjahr: Int = 2010
    im_kino_gesehen: Bool = true

    print("Film: " + titel)
}

fn berechne_gesamtkosten(stunden: Decimal, stundensatz: Decimal) -> Decimal {
    return stunden * stundensatz
}

fn main() {
    arbeitszeit = decimal("3.500000000")
    satz = decimal("95.000000000")
    gesamt = berechne_gesamtkosten(arbeitszeit, satz)
    print(gesamt)
}

Kapitel 6: Variablen und Unveränderlichkeit

fn main() {
    benutzername = "senior_coder_42"
    print("Angemeldeter Benutzer: " + benutzername)
}

fn main() {
    mutable punktestand = 100
    print("Start-Punktestand: " + punktestand)

    punktestand = punktestand - 15
    print("Nach Strafe (-15):  " + punktestand)

    punktestand = punktestand + 30
    print("Nach Bonus (+30):   " + punktestand)
}

Kapitel 7: Operatoren und Ausdrücke

fn main() {
    ist_gerade = (10 % 2 == 0)
    print(ist_gerade) # Ausgabe: true
}

fn im_arbeitsfaehigen_alter(alter: Int) -> Bool {
    return alter >= 18 && alter <= 65
}

fn main() {
    print(im_arbeitsfaehigen_alter(25)) # true
    print(im_arbeitsfaehigen_alter(16)) # false
}

fn qualifiziert_fuer_rabatt(is_vip: Bool, bestellwert: Decimal, ist_neukunde: Bool) -> Bool {
    return is_vip || (bestellwert > decimal("100.000000000") && !ist_neukunde)
}

fn main() {
    print(qualifiziert_fuer_rabatt(false, decimal("150.000000000"), false)) # true
    print(qualifiziert_fuer_rabatt(false, decimal("150.000000000"), true))  # false (Neukunde)
    print(qualifiziert_fuer_rabatt(true, decimal("20.000000000"), true))   # true (VIP sticht immer)
}

Kapitel 8: Ein- und Ausgaben

fn main() {
    print("================================")
    print(" Name:  Dr. Stefanie Code")
    print(" Beruf: Lead Software Architect")
    print(" Mail:  stefanie@example.com")
    print("================================")
}

fn drucke_aufgabe(id: Int, name: String, erledigt: Bool) {
    status_label = if erledigt { "[X] ERLEDIGT" } else { "[ ] OFFEN" }
    print("----------------------------------------")
    print("Aufgabe #" + id + ": " + name)
    print("Status:      " + status_label)
    print("----------------------------------------")
}

fn main() {
    drucke_aufgabe(42, "Refactoring der Rechnungsmodule", false)
}

Kapitel 9: Entscheidungen mit Bedingungen

fn ist_volljaehrig(alter: Int) -> Bool {
    return alter >= 18
}

fn main() {
    print(ist_volljaehrig(17)) # false
    print(ist_volljaehrig(18)) # true
}

fn monats_tage(monat: Int) -> Int {
    return match monat {
        1 => 31,
        2 => 28,
        3 => 31,
        4 => 30,
        5 => 31,
        6 => 30,
        7 => 31,
        8 => 31,
        9 => 30,
        10 => 31,
        11 => 30,
        12 => 31,
        _ => 0,
    }
}

fn main() {
    print(monats_tage(2))  # 28
    print(monats_tage(10)) # 31
    print(monats_tage(99)) # 0 (Ungültiger Monat)
}

fn pruefe_passwort_einfach(pw: String) -> Bool {
    if pw == "12345678" || pw == "passwort" || pw == "admin123" {
        return false
    }
    return len(pw) >= 8
}

fn main() {
    print(pruefe_passwort_einfach("12345678"))       # false
    print(pruefe_passwort_einfach("kurz"))           # false
    print(pruefe_passwort_einfach("meinSicheres#26")) # true
}

Kapitel 10: Wiederholungen und Schleifen

fn main() {
    mutable count = 10
    while count >= 1 {
        print(count)
        count = count - 1
    }
    print("Rakete gestartet!")
}

fn main() {
    zahlen: Int[] = [10, 20, 30, 40]
    mutable summe = 0
    for z in zahlen {
        summe = summe + z
    }
    print("Gesamtsumme: " + summe) # 100
}

fn main() {
    liste: Int[] = [3, 9, 14, 42, 55, 88]
    mutable gefunden = false

    for element in liste {
        if element == 42 {
            gefunden = true
            break
        }
    }

    if gefunden {
        print("Gefunden! Die Antwort auf alle Fragen ist im Array.")
    } else {
        print("Nicht gefunden")
    }
}

Kapitel 11: Funktionen und Prozeduren

fn verdopple(zahl: Int) -> Int {
    return zahl * 2
}

fn main() {
    print(verdopple(21)) # 42
}

fn ist_dringend(verbleibende_tage: Int) -> Bool {
    return verbleibende_tage < 3
}

fn main() {
    print(ist_dringend(1)) # true
    print(ist_dringend(5)) # false
}

fn status_symbol(erledigt: Bool) -> String {
    if erledigt {
        return "[OK]"
    }
    return "[OFFEN]"
}

fn main() {
    print(status_symbol(true))  # [OK]
    print(status_symbol(false)) # [OFFEN]
}

Kapitel 12: Verträge und Vorbedingungen (Design by Contract)

fn quadratwurzel_naiv(x: Int) -> Int
    requires { x >= 0 }
{
    mutable r = 0
    while (r + 1) * (r + 1) <= x {
        r = r + 1
    }
    return r
}

fn main() {
    print(quadratwurzel_naiv(49)) # 7
}

fn begrenze(wert: Int, min_wert: Int, max_wert: Int) -> Int
    requires { min_wert <= max_wert }
    ensures { result >= min_wert && result <= max_wert }
{
    if wert < min_wert { return min_wert }
    if wert > max_wert { return max_wert }
    return wert
}

fn main() {
    print(begrenze(125, 0, 100)) # 100
    print(begrenze(-10, 0, 100)) # 0
    print(begrenze(42, 0, 100))  # 42
}

fn prozentsatz(teil: Int, gesamt: Int) -> Int
    requires { gesamt > 0 && teil >= 0 && teil <= gesamt }
    ensures { result >= 0 && result <= 100 }
{
    return (teil * 100) / gesamt
}

fn main() {
    print(prozentsatz(15, 60)) # 25
}

Kapitel 13: Sammlungen, Listen und Wörterbücher (Arrays & Maps)

fn main() {
    themen: String[] = ["Compiler", "Datenbanken", "Web-Sicherheit"]
    for t in themen {
        print("- " + t)
    }
}

fn main() {
    mutable preise: Map<String, Int> = map()
    preise = set(preise, "Espresso", 2)
    preise = set(preise, "Cappuccino", 4)

    match get(preise, "Espresso") {
        Some(preis) => print("Espresso kostet " + preis + " Euro"),
        None => print("Artikel nicht gefunden"),
    }

    match get(preise, "Kuchen") {
        Some(preis) => print("Kuchen kostet " + preis + " Euro"),
        None => print("Kuchen ist leider ausverkauft"),
    }
}

fn zaehle_woerter(liste: String[]) -> Map<String, Int> {
    mutable zaehler: Map<String, Int> = map()
    for wort in liste {
        aktuell = match get(zaehler, wort) {
            Some(anzahl) => anzahl + 1,
            None => 1,
        }
        zaehler = set(zaehler, wort, aktuell)
    }
    return zaehler
}

fn main() {
    begriffe: String[] = ["zelyra", "rust", "zelyra", "web"]
    ergebnis = zaehle_woerter(begriffe)
    print("Erledigt.")
}

Kapitel 14: Eigene Datentypen erstellen (Records & Tables)

type UserId = Id

fn main() {
    uid: UserId = 1
    print("Benutzer-ID angelegt: " + uid)
}

table kategorien {
    id: Id primary auto
    kategorie_name: String required
    beschreibung: String
}

table notizen {
    id: Id primary auto
    aufgabe_id: Id required
    notiz_text: String required
    erstellt_am: Timestamp auto
}

Kapitel 15: Module und Code-Organisation

zelyra new task_manager
cd task_manager
ls -la

Erklärung: Das Projekt enthält zelyra.toml (Konfiguration), main.zyl (Einstiegspunkt) und Verzeichnisse für modulare Quelldateien.

[project]
name = "task_manager"
version = "0.3.0"
description = "Zuverlässige Aufgabenverwaltung mit Zelyra"
authors = ["Stefan Siedelmann"]

fn initialisiere_app() -> String {
    return "TaskManager bereit"
}

fn verarbeite_aufgabe(titel: String) -> String {
    return "Verarbeite: " + titel
}

fn zeige_status(nachricht: String) {
    print("[STATUS] " + nachricht)
}

fn main() {
    zeige_status(initialisiere_app())
    zeige_status(verarbeite_aufgabe("Release vorbereiten"))
}

Kapitel 16: Fehlerarten und ihre Ursachen

fn main() {
    # Falsch: anzahl: Int = "zehn"  -> E-TYPE-001
    # Korrekt:
    anzahl: Int = 10
    print(anzahl)
}

fn pruefe_kinofreigabe(alter: Int) -> Bool
    requires { alter >= 0 && alter <= 130 }
{
    return alter >= 16
}

fn main() {
    print(pruefe_kinofreigabe(17)) # true
}

Kapitel 17: Fehler als Werte – Das Result-Muster

fn pruefe_gerade(zahl: Int) -> Result<Int, String> {
    if zahl % 2 == 0 {
        return Ok(zahl)
    }
    return Err("Die Zahl ist ungerade!")
}

fn main() {
    match pruefe_gerade(10) {
        Ok(z) => print("Erfolg: " + z + " ist gerade"),
        Err(msg) => print("Fehler: " + msg),
    }
}

fn validiere_benutzername(name: String) -> Result<String, String> {
    if name == "" {
        return Err("Name darf nicht leer sein.")
    }
    if name == "admin" || name == "root" {
        return Err("Name ist reserviert.")
    }
    return Ok(name)
}

fn main() {
    match validiere_benutzername("stefan") {
        Ok(n) => print("Willkommen, " + n),
        Err(e) => print("Ungueltiger Benutzername: " + e),
    }
}

fn sichere_division(zaehler: Int, nenner: Int) -> Result<Int, String> {
    if nenner == 0 {
        return Err("Division durch null ist verboten!")
    }
    return Ok(zaehler / nenner)
}

fn main() {
    match sichere_division(100, 5) {
        Ok(quotient) => {
            verdoppelt = quotient * 2
            print("Ergebnis verdoppelt: " + verdoppelt)
        },
        Err(e) => print("Berechnungsfehler: " + e),
    }
}

Kapitel 18: Das Nichts existiert nicht – Der sichere Umgang mit Option

fn finde_partner(name: String) -> Option<String> {
    if name == "Romeo" {
        return Some("Julia")
    }
    if name == "Bonnie" {
        return Some("Clyde")
    }
    return None
}

fn main() {
    match finde_partner("Romeo") {
        Some(partner) => print("Gefunden: " + partner),
        None => print("Kein Partner hinterlegt"),
    }
}

fn main() {
    zahlen: Int[] = [10, 20, 30]
    match last(zahlen) {
        Some(wert) => print("Letztes Element: " + wert),
        None => print("Achtung: Liste war leer!"),
    }
}

fn finde_index(liste: Int[], ziel: Int) -> Option<Int> {
    mutable idx = 0
    for element in liste {
        if element == ziel {
            return Some(idx)
        }
        idx = idx + 1
    }
    return None
}

fn main() {
    daten: Int[] = [100, 200, 300, 400]
    match finde_index(daten, 300) {
        Some(pos) => print("Gefunden an Index: " + pos),
        None => print("Element nicht in Liste"),
    }
}

Kapitel 19: Tests und Qualitätssicherung

fn addiere(a: Int, b: Int) -> Int {
    return a + b
}

fn main() {
    assert(addiere(2, 3) == 5)
    assert(addiere(-2, 2) == 0)
    assert(addiere(0, 0) == 0)
    print("Alle Tests fuer addiere() bestanden!")
}

fn finde_index(liste: Int[], ziel: Int) -> Option<Int> {
    mutable idx = 0
    for element in liste {
        if element == ziel {
            return Some(idx)
        }
        idx = idx + 1
    }
    return None
}

fn main() {
    test_liste: Int[] = [10, 20, 30]
    match finde_index(test_liste, 20) {
        Some(i) => assert(i == 1),
        None => assert(false),
    }
    match finde_index(test_liste, 99) {
        Some(_) => assert(false),
        None => assert(true),
    }
    print("Suchtests erfolgreich!")
}

fn validiere_titel(t: String) -> Bool {
    return len(t) >= 3 && len(t) <= 50
}

fn main() {
    assert(validiere_titel("OK") == false)
    assert(validiere_titel("Gueltiger Titel") == true)
    assert(validiere_titel("Ein viel zu langer Titel, der mehr als fuenfzig Zeichen umfasst und daher abgewiesen werden muss") == false)
    print("Validierungs-Suite erfolgreich ausgefuehrt.")
}

Kapitel 20: Arbeiten mit Dateien

fn main() uses FileSystem {
    ergebnis = write_text("hallo.txt", "Hallo aus der sicheren Zelyra-Welt!")
    match ergebnis {
        Ok(_) => print("Datei erfolgreich geschrieben."),
        Err(e) => print("Schreibfehler: " + e),
    }
}

fn main() uses FileSystem {
    match read_text("hallo.txt") {
        Ok(inhalt) => print("Gelesener Inhalt: " + inhalt),
        Err(e) => print("Konnte Datei nicht lesen: " + e),
    }
}

fn logge_ereignis(pfad: String, meldung: String) uses FileSystem {
    bisher = match read_text(pfad) {
        Ok(alt) => alt + "
",
        Err(_) => "",
    }
    neu = bisher + "[LOG] " + meldung
    write_text(pfad, neu)
}

fn main() uses FileSystem {
    logge_ereignis("audit.log", "System gestartet.")
    logge_ereignis("audit.log", "Benutzer angemeldet.")
    print("Log aktualisiert.")
}

Kapitel 21: Datum, Uhrzeit, Zufall und strukturierte Daten

fn wuerfeln() -> Int uses Random {
    return random_int(1, 6)
}

fn main() uses Random {
    augen = wuerfeln()
    print("Gewuerfelt: " + augen)
}

fn main() {
    codes: Int[] = [200, 201, 404, 500]
    json_text = json_encode(codes)
    print("JSON: " + json_text)
}

fn main() uses Clock, FileSystem {
    aktueller_zeitpunkt = now()
    logzeile = "Ereignis eingetreten um: " + aktueller_zeitpunkt
    write_text("zeitstempel.log", logzeile)
    print("Zeitstempel geloggt.")
}

Kapitel 22: Nebenläufigkeit und Hintergrundaufgaben

fn berechne_teil_a() -> Int { return 20 + 1 }
fn berechne_teil_b() -> Int { return 20 + 1 }

fn main() {
    parallel {
        task_a = berechne_teil_a()
        task_b = berechne_teil_b()
    }
    summe = await(task_a) + await(task_b)
    print("Paralleles Gesamtergebnis: " + summe) # 42
}

fn lade_kunden_anzahl() -> Int { return 150 }
fn lade_offene_rechnungen() -> Int { return 12 }

fn main() {
    parallel {
        ka = lade_kunden_anzahl()
        re = lade_offene_rechnungen()
    }
    print("Kunden: " + await(ka) + ", Offene Rechnungen: " + await(re))
}

Kapitel 23: Warum Zelyra die Datenbank direkt versteht

database MariaDB {
    url: env("DATABASE_URL")
}

table benutzer {
    id: Id primary auto
    email: String required
    aktiv: Bool required
}

fn lade_aktive_benutzer() -> benutzer[] uses Database {
    return sql<benutzer[]> {
        SELECT * FROM benutzer WHERE aktiv = true
    }
}

Kapitel 24: Tabellen definieren und Daten modellieren

table etiketten {
    id: Id primary auto
    name: String(30) required
}

table kunden {
    id: Id primary auto
    vorname: String(50) required
    nachname: String(50) required
    email: Email required
    telefon: String(30)
}

table kommentare {
    id: Id primary auto
    aufgabe_id: Id required fk tasks(id) on_delete restrict
    kommentar: String required
    erstellt_am: Timestamp auto
}

Kapitel 25: Daten abfragen und verändern

fn lade_offene_aufgaben() -> tasks[] uses Database {
    return sql<tasks[]> {
        SELECT * FROM tasks WHERE erledigt = false ORDER BY id ASC
    }
}

fn loesche_aufgabe(aufgabe_id: Id) uses Database {
    sql {
        DELETE FROM tasks WHERE id = :aufgabe_id
    }
}

fn archiviere_und_neue_aufgabe(alte_id: Id, neuer_titel: String) uses Database {
    transaction {
        sql {
            UPDATE tasks SET archiviert = true WHERE id = :alte_id
        }
        sql {
            INSERT INTO tasks (titel, erledigt, archiviert)
            VALUES (:neuer_titel, false, false)
        }
    }
}

Kapitel 26: Webseiten ausgeben

page "/ueber-uns" {
    html {
        <main>
            <h1>Ueber unser Unternehmen</h1>
            <p>Wir bauen langlebige Software mit Zelyra.</p>
        </main>
    }
}

page "/produkt/{nummer: Int}" {
    html {
        <div>
            <h2>Produkt-Detailansicht</h2>
            <p>Angezeigte Artikelnummer: {nummer}</p>
        </div>
    }
}

page "/uebersicht" {
    html {
        <nav>
            <a href="/">Startseite</a> | <a href="/ueber-uns">Ueber uns</a>
        </nav>
        <section>
            <h2>Unsere Kernbereiche</h2>
            <ul>
                <li>Sichere Web-Entwicklung</li>
                <li>Transaktionale Datenbanken</li>
                <li>KI-gestuetzte Codeanalyse</li>
            </ul>
        </section>
    }
}

Kapitel 27: Formulare und Benutzereingaben

form KategorieForm {
    name: String required
    beschreibung: String
}

zelyra form validate main.zyl

Erklärung: Zelyra prüft die Formularfelder gegen das zugrundeliegende Tabellenschema.

form AufgabeForm {
    titel: String required min_length(3)
    prioritaet: Int required min(1) max(3)
}

Kapitel 28: Das vollständige CRUD-Muster

crud Kategorie -> kategorien {
    title: "Kategorien verwalten"
    fields: [kategorie_name, beschreibung]
}

zelyra routes main.zyl

Erklärung: Die Ausgabe zeigt alle automatisch generierten Routen wie GET /kategorien, GET /kategorien/new, POST /kategorien/new, GET /kategorien/{id} und POST /kategorien/{id}/delete.

action "duplizieren" on tasks (id: Id) uses Database {
    sql {
        INSERT INTO tasks (titel, erledigt)
        SELECT CONCAT(titel, ' (Kopie)'), false FROM tasks WHERE id = :id
    }
}

Kapitel 29: Benutzer, Passwörter und Sitzungen

zelyra auth hash-password "MeinSuperSicheresPasswort2026!"

page "/einstellungen" requires auth {
    html {
        <h1>Persoenliche Benutzereinstellungen</h1>
    }
}

page "/admin/system" requires auth permits admin {
    html {
        <h1>System-Administration (Nur fuer Admins)</h1>
    }
}

Kapitel 30: APIs und Datenaustausch

page "/api/version" {
    json {
        "system": "Zelyra TaskEngine",
        "version": "1.0.5",
        "status": "operational"
    }
}

page "DELETE /api/tasks/{id: Id}" uses Database {
    betroffene = sql {
        DELETE FROM tasks WHERE id = :id
    }
    if betroffene == 0 {
        return http_response(404, "Aufgabe nicht gefunden")
    }
    return http_response(200, "Aufgabe geloescht")
}

zelyra doc --openapi main.zyl > openapi.json

Erklärung: Erzeugt eine standardkonforme OpenAPI-3.0-Spezifikation aus deinen deklarierten Routen, Tabellen und Typen.

Kapitel 31: Lesbarkeit als oberstes Gebot

zelyra fmt src/main.zyl

# Schlecht: fn f(a: Int, b: Float) -> Float { return a * b * 0.19 }
# Vorbildlich:
fn berechne_mehrwertsteuer(netto_betrag: Decimal, steuersatz: Decimal) -> Decimal {
    return netto_betrag * steuersatz
}

Kapitel 32: KI-Nativität – Warum Zelyra perfekt für KI-Assistenten ist

zelyra check --format json main.zyl

zelyra impact main.zyl

Erklärung: Analysiert Abhängigkeiten und zeigt, welche Funktionen oder Tabellen von einer Änderung betroffen sind.

fn berechne_rabatt(preis: Decimal) -> Decimal {
    return _
}

Führe zelyra check aus. Der Compiler antwortet mit einem präzisen Loch-Report: Er nennt dir den erwarteten Rückgabetyp Decimal und alle im Gültigkeitsbereich verfügbaren Bezeichner – die perfekte Vorlage für einen KI-Assistenten!

Kapitel 33: Sicherheit durch Fähigkeiten (Capabilities)

fn speichere_backup_protokoll(meldung: String) uses Clock, Environment, FileSystem {
    zeit = now()
    pfad = match env("BACKUP_LOG_PATH") {
        Some(p) => p,
        None => "backup.log",
    }
    write_text(pfad, "[" + zeit + "] " + meldung)
}

Kapitel 34: Zelyra im Vergleich

def verdopple(x): return x * 2

Zelyra:

fn verdopple(x: Int) -> Int {
    return x * 2
}

Kapitel 35: Software planen – Von der Idee zum Entwurf

table notizen_app {
    id: Id primary auto
    benutzer_id: Id required
    titel: String(100) required
    inhalt: String required
    erstellt_am: Timestamp auto
}

fn erstelle_notiz(titel: String, text: String) -> Bool
    requires { len(titel) >= 1 && len(titel) <= 100 }
    requires { len(text) > 0 }
    ensures { result == true }
{
    return true
}

Kapitel 36: Architektur und saubere Codestruktur

  1. Präsentation: page, html, form
  2. Geschäftslogik: Reine Funktionen (fn berechne...) mit Verträgen
  3. Persistenz: table, sql, transaction

Kapitel 37: Konfiguration und Umgebungsvariablen

fn main() uses Environment {
    match env("USER_NAME") {
        Some(name) => print("Hallo, " + name + "!"),
        None => print("Hallo, lieber Gast!"),
    }
}

fn hole_env_oder_standard(schluessel: String, standard: String) -> String uses Environment {
    return match env(schluessel) {
        Some(wert) => wert,
        None => standard,
    }
}

fn main() uses Environment {
    port = hole_env_oder_standard("APP_PORT", "8080")
    print("Server lauscht auf Port: " + port)
}

fn ist_produktionsmodus() -> Bool uses Environment {
    return match env("APP_ENV") {
        Some(modus) => modus == "production",
        None => false,
    }
}

fn main() uses Environment {
    if ist_produktionsmodus() {
        print("Produktionsmodus aktiv: Strenger Sicherheitsmodus.")
    } else {
        print("Entwicklungsmodus aktiv: Ausfuehrliche Fehlermeldungen.")
    }
}

Kapitel 38: Fehlersuche und Optimierung

zelyra doctor

Kapitel 39: Bereitstellung und Betrieb

zelyra serve main.zyl 127.0.0.1:3000

services:
  mariadb:
    image: mariadb:11.4
    environment:
      MARIADB_ROOT_PASSWORD: secret
      MARIADB_DATABASE: app_db
    ports:
      - "3306:3306"

zelyra db plan main.zyl
# Prüfe die SQL-Änderungen sorgfältig!
zelyra db apply main.zyl

Kapitel 40: Das große Abschlussprojekt: Vollständige Aufgabenverwaltung

zelyra check main.zyl

Der Compiler bestätigt 0 Fehler und 0 Warnungen.

table tasks {
    id: Id primary auto
    titel: String(100) required
    erledigt: Bool required
    faellig_am: Date
}

Passe das Formular und die HTML-Ansicht an, um das Datumsfeld darzustellen.

Kapitel 41: Funktionsumfang und sicherer Betrieb

zelyra --version
zelyra doctor

Erklärung: Bestätigt, dass Version 1.0.5 aktiv ist, die Sprachkompatibilität auf 0.1 steht und das Docker Compose v2 Plugin bereitsteht.

zelyra --tutorial invoice --no-start
cd invoice-tutorial
zelyra db plan main.zyl

Erklärung: db plan analysiert das deklarierte Rechnungsschema (Kunden, Artikel, Rechnungen, Positionen) und gibt die geplanten SQL-Statements aus, ohne schreibend in die Datenbank einzugreifen.

  1. Test-Datenbank über einen alternativen Port starten (z. B. 3307 in .env).
  2. zelyra db plan main.zyl prüfen.
  3. Schema mit zelyra db apply main.zyl auf der Testdatenbank anwenden.
  4. Backup-Erstellung mit zelyra db backup testen.
  5. Erst nach erfolgreicher Test-Verifikation wird das Update für das Produktivsystem freigegeben.

Kapitel 42: Dein Weg als Zelyra-Entwickler

table buchungen {
    id: Id primary auto
    datum: Date required
    kategorie: String(50) required
    betrag: Decimal required
    beschreibung: String
}

fn buchung_gueltig(betrag: Decimal) -> Bool
    ensures { result == (betrag != decimal("0.000000000")) }
{
    return betrag != decimal("0.000000000")
}

Erklärung: Buchungen mit einem Betrag von 0,00 € werden durch die Nachbedingung logisch ausgeschlossen.

Kapitel 43: Mit Zelyra Studio arbeiten

cd mein_projekt
zelyra editor .

Erklärung: Studio startet einen lokalen Webserver auf 127.0.0.1 mit sicherem Einmal-Token und öffnet den Editor im Standardbrowser.

  1. Wähle im Studio eine deklarierte Tabelle ohne bestehende CRUD-Ansicht aus.
  2. Starte den CRUD-Assistenten und wähle die gewünschten Formularfelder.
  3. Betrachte die vorgeschlagene Quelltext-Differenz (Diff) in der Vorschau.
  4. Vergleiche die generierten Endpunkte mit zelyra routes main.zyl im Terminal.
  5. Übernimm die Änderung erst nach Prüfung im Editor.

Anhang I: Häufige Fragen und Antworten (FAQ)

Frage: Wie verwende ich Imports? Antwort: Mit import "src/models.zyl" as models bindest du eine projektlokale Quelldatei ein. Unterstützte öffentliche Deklarationen werden über den Modulnamen angesprochen. Eine Paketregistrierung, dynamische Imports und ein vollständiger Deployment-Abschluss sind nicht enthalten.

Frage: Kann ich mit Zelyra auch reine Konsolenprogramme schreiben? Antwort: Ja. print() gibt Werte aus. read_console("Prompt: ") liest eine Zeile und liefert String?; dafür braucht die Funktion uses Console und das Projekt gegebenenfalls console = true.

Frage: Warum unterstützt Zelyra MariaDB als bevorzugte Engine? Antwort: MariaDB bietet herausragende Performance, Open-Source-Freiheit, Stabilität und breite Cloud-Unterstützung für professionelle Webanwendungen.

Anhang J: Weiterführende Ressourcen und Community

Anhang K: Das Zelyra-Cookbook (Praxisrezepte)

Das Zelyra-Cookbook bietet eine kuratierte Sammlung erprobter Entwurfsmuster und praktischer Lösungen für reale Anforderungen in Unternehmens- und Webanwendungen. Jedes Rezept folgt dem bewährten Dreischritt: Problem, Lösung (vertraglich abgesicherter Zelyra-Code) und Erklärung.

Teil 1: Datenverarbeitung & Standardbibliothek

Rezept K.1: Exakte kaufmännische Rundung und Skontoberechnung

Problem: In kaufmännischen Anwendungen führen Fließkommazahlen (Float) zu Rundungsfehlern bei Rechnungsrabatten, Skontoabzügen und der Mehrwertsteueraufteilung.

Lösung:

pub record DiscountResult {
    base_net: Decimal,
    discount_rate: Decimal,
    discount_amount: Decimal,
    final_net: Decimal,
}

pub fn apply_cash_discount(amount: Decimal, rate: Decimal) -> DiscountResult
    requires { amount >= decimal("0.00") && rate >= decimal("0.00") && rate <= decimal("100.00") }
    ensures { result.final_net <= result.base_net && result.discount_amount >= decimal("0.00") }
{
    let discount = (amount * rate) / decimal("100.00")
    let final_amount = amount - discount
    return DiscountResult {
        base_net: amount,
        discount_rate: rate,
        discount_amount: discount,
        final_net: final_amount,
    }
}

Erklärung:

Rezept K.2: Webhook-Payloads sicher parsen und typisieren

Problem: Ein externer Zahlungsdienstleister (z. B. Stripe oder PayPal) sendet JSON-Payloads via HTTP-POST an einen Webhook-Endpunkt. Unvollständige oder manipulierte Felder müssen sicher abgewehrt werden.

Lösung:

pub enum PaymentStatus {
    Paid,
    Pending,
    Failed,
}

pub record WebhookPayload {
    event_id: String,
    payment_reference: String,
    amount: Decimal,
    status: PaymentStatus,
}

pub fn parse_payment_status(raw: String) -> Option<PaymentStatus> {
    match raw {
        "succeeded" => { return Option::Some(PaymentStatus::Paid) }
        "processing" => { return Option::Some(PaymentStatus::Pending) }
        "requires_payment_method" => { return Option::Some(PaymentStatus::Failed) }
        _ => { return Option::None }
    }
}

Erklärung:

Rezept K.3: Fristen und Fälligkeitstage berechnen

Problem: Eine Rechnung erhält ein Zahlungsziel von 14 Tagen. Fällt der Fälligkeitstag auf ein Wochenende, soll die Frist automatisch auf den nächsten Werktag (Montag) verlängert werden.

Lösung:

pub fn calculate_due_date(invoice_date: Date, net_days: Int) -> Date
    requires { net_days >= 0 }
{
    let target = invoice_date.add_days(net_days)
    let weekday = target.day_of_week()
    if weekday == 6 {
        return target.add_days(2)
    } else if weekday == 7 {
        return target.add_days(1)
    } else {
        return target
    }
}

Erklärung:

Teil 2: Datenbank, Transaktionen & Mandanten

Rezept K.4: Lückenlose Rechnungsnummernkreise (Atomic Sequence)

Problem: Das Finanzamt und die GoBD fordern für Rechnungen eine lückenlose, fortlaufende Nummerierung. Unter parallelen Anfragen können Race-Conditions zu doppelten oder fehlenden Nummern führen.

Lösung:

table invoice_sequences scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    fiscal_year: Int required
    current_value: Int required default 0

    unique within tenant fiscal_year
}

fn next_invoice_number(t_id: TenantId, year: Int) -> String uses Database {
    transaction {
        let seq = query_one(
            "SELECT id, current_value FROM invoice_sequences WHERE tenant_id = ? AND fiscal_year = ? FOR UPDATE",
            [t_id, year]
        )
        let next_val = seq.current_value + 1
        execute(
            "UPDATE invoice_sequences SET current_value = ? WHERE id = ?",
            [next_val, seq.id]
        )
        return "RE-" + year.to_string() + "-" + next_val.to_string()
    }
}

Erklärung:

Rezept K.5: Revisionssicherer Audit-Trail (Temporal Ledger)

Problem: Jede Preis- oder Statusänderung an schützenswerten Datensätzen muss unveränderlich mit ausführendem Benutzer und Zeitstempel dokumentiert werden.

Lösung:

table audit_ledger scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    actor_id: Id required
    entity_name: String(64) required
    entity_id: Id required
    action_type: String(32) required
    payload_hash: String(64) required
    created_at: Instant required
}

fn record_audit_entry(
    t_id: TenantId,
    actor: Id,
    entity: String,
    target_id: Id,
    action: String,
    raw_payload: String
) uses Database, Clock {
    let now_ts = now()
    let hash = hash_sha256(raw_payload)
    execute(
        "INSERT INTO audit_ledger (tenant_id, actor_id, entity_name, entity_id, action_type, payload_hash, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
        [t_id, actor, entity, target_id, action, hash, now_ts]
    )
}

Erklärung:

Rezept K.6: Keyset-Paginierung für große Tabellen

Problem: Bei Tabellen mit Millionen Zeilen führt SELECT ... LIMIT 50 OFFSET 500000 zu spürbaren Datenbanklatenzen, da die Datenbank alle übersprungenen Zeilen sequenziell einlesen muss.

Lösung:

table customer_logs scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    created_at: Instant required
    message: String(255) required

    index idx_tenant_cursor (tenant_id, created_at, id)
}

fn fetch_log_page(t_id: TenantId, last_ts: Instant, last_id: Id, page_size: Int) -> CustomerLog[] uses Database {
    return query(
        "SELECT id, tenant_id, created_at, message FROM customer_logs WHERE tenant_id = ? AND (created_at < ? OR (created_at = ? AND id < ?)) ORDER BY created_at DESC, id DESC LIMIT ?",
        [t_id, last_ts, last_ts, last_id, page_size]
    )
}

Erklärung:

Teil 3: Sicherheit, Authentifizierung & Governance

Rezept K.7: TOTP-Zwei-Faktor-Authentifizierung (2FA)

Problem: Sensible Benutzerkonten müssen durch RFC-6238-basierte Einmalkennwörter (Time-Based One-Time Passwords) und sichere Wiederherstellungscodes geschützt werden.

Lösung:

table user_mfa_settings scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    user_id: Id required unique
    secret_key: String(64) required
    is_enabled: Bool required default false
    backup_code_hash: String(128) required
}

fn verify_totp_attempt(user_secret: String, user_token: String) -> Bool uses Clock {
    let valid = totp_verify(user_secret, user_token, 30)
    return valid
}

Erklärung:

Rezept K.8: Mandantengebundene API mit Rollenprüfung

Problem: Eine JSON-API zur Freigabe von Belegen muss sicherstellen, dass Benutzer nur Daten des eigenen Mandanten manipulieren und zwingend über die Rolle AccountingManager verfügen.

Lösung:

table vouchers scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    voucher_number: String(40) required
    status: String(20) required default "draft"
    total_amount: Decimal(12, 2) required
}

api approve_voucher(voucher_id: Id) scoped by tenant_id {
    permission: "vouchers.approve"
    validates {
        voucher_id > 0: "Ungültige Beleg-ID."
    }

    execute uses Database {
        transaction {
            let row = query_one(
                "SELECT id, status FROM vouchers WHERE id = ? AND tenant_id = ? FOR UPDATE",
                [voucher_id, session.tenant_id]
            )
            if row.status == "approved" {
                return { success: false, error: "Beleg ist bereits freigegeben." }
            }
            execute(
                "UPDATE vouchers SET status = 'approved' WHERE id = ? AND tenant_id = ?",
                [voucher_id, session.tenant_id]
            )
            return { success: true, message: "Beleg erfolgreich genehmigt." }
        }
    }
}

Erklärung:

Rezept K.9: Schutz vor Brute-Force durch Ratenbegrenzung

Problem: Passwort-Reset- und Login-Endpunkte müssen vor Wörterbuchangriffen und Credential-Stuffing geschützt werden.

Lösung:

table rate_limits {
    id: Id primary auto
    client_ip: String(45) required
    action: String(30) required
    attempts: Int required default 1
    locked_until: Instant?

    index idx_client_action (client_ip, action)
}

fn check_rate_limit(ip: String, action_name: String, max_attempts: Int) -> Bool uses Database, Clock {
    let now_ts = now()
    let record = query_one_optional(
        "SELECT id, attempts, locked_until FROM rate_limits WHERE client_ip = ? AND action = ?",
        [ip, action_name]
    )
    match record {
        Option::Some(r) => {
            if r.attempts >= max_attempts {
                return false
            }
            execute("UPDATE rate_limits SET attempts = attempts + 1 WHERE id = ?", [r.id])
            return true
        }
        Option::None => {
            execute("INSERT INTO rate_limits (client_ip, action, attempts) VALUES (?, ?, 1)", [ip, action_name])
            return true
        }
    }
}

Erklärung:

Teil 4: Web, CRUD & Master-Detail

Rezept K.10: Master-Detail-Rechnungsformular mit Positionen (has_many)

Problem: Ein Rechnungsbeleg besteht aus Kopfdaten (Kunde, Rechnungsdatum) und einer Liste beliebig vieler Belegpositionen, die gemeinsam in einer Transaktion gespeichert und aufsummiert werden müssen.

Lösung:

table invoices scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    invoice_number: String(32) required unique within tenant
    invoice_date: Date required
    customer_name: String(100) required
    total_net: Decimal(12, 2) required default decimal("0.00")
    total_gross: Decimal(12, 2) required default decimal("0.00")
}

table invoice_items scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    invoice: Invoice required on_delete cascade
    description: String(120) required
    quantity: Decimal(8, 2) required
    unit_price: Decimal(10, 2) required
    line_total: Decimal(12, 2) required
}

crud Invoice -> invoices {
    title: "Rechnung erfassen"

    has_many items: InvoiceItem {
        title: "Rechnungspositionen"
        fields: [description, quantity, unit_price, line_total]
    }

    aggregates {
        total_net = sum(items.line_total)
        total_gross = sum(items.line_total) * decimal("1.19")
    }
}

Erklärung:

Rezept K.11: GoBD-Schutz mit Lifecycle-Guards

Problem: Rechnungen, die bereits an den Kunden versandt oder bezahlt wurden, dürfen aus steuerrechtlichen Gründen nicht mehr nachträglich verändert oder gelöscht werden.

Lösung:

table sales_invoices scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    doc_number: String(30) required
    is_finalized: Bool required default false
    is_cancelled: Bool required default false
}

crud SalesInvoice -> sales_invoices {
    title: "Ausgangsrechnungen"

    guard edit when is_finalized == true {
        error: "Festgeschriebene Belege können nicht mehr editiert werden. Bitte Stornobuchung durchführen."
    }

    guard delete when is_finalized == true {
        error: "Festgeschriebene Rechnungen dürfen gemäß GoBD niemals gelöscht werden."
    }
}

Erklärung:

Rezept K.12: Feldübergreifende Invariantenprüfungen (validate)

Problem: Bei Hotel- oder Fahrzeugbuchungen darf das Abreisedatum niemals vor oder am Anreisedatum liegen.

Lösung:

table hotel_bookings scoped by tenant_id: TenantId {
    id: Id primary auto
    tenant_id: TenantId required
    guest_name: String(100) required
    check_in: Date required
    check_out: Date required
    rooms_count: Int required default 1

    validate {
        check_out > check_in: "Das Abreisedatum muss nach dem Anreisedatum liegen."
        rooms_count >= 1 && rooms_count <= 10: "Es können maximal 10 Zimmer pro Buchung reserviert werden."
    }
}

Erklärung:

Teil 5: Hintergrund-Dienste, E-Mail & Export

Rezept K.13: Transaktionale PDF-Erstellung und Mail-Outbox

Problem: Nach Abschluss einer Bestellung muss eine PDF-Auftragsbestätigung erzeugt und per E-Mail versandt werden. Schlägt die Datenbanktransaktion fehl, darf keine E-Mail versendet werden.

Lösung:

fn finalize_order(order_id: Id, recipient_mail: String) uses Database {
    transaction {
        let order = query_one("SELECT id, order_number, total_gross FROM orders WHERE id = ?", [order_id])
        let pdf_bytes = render_pdf("templates/OrderConfirmation.html", order)
        mail_queue(
            recipient_mail,
            "Ihre Auftragsbestätigung " + order.order_number,
            "Vielen Dank für Ihre Bestellung. Im Anhang finden Sie Ihre Bestätigung.",
            order.order_number + ".pdf",
            pdf_bytes
        )
        execute("UPDATE orders SET status = 'confirmed' WHERE id = ?", [order_id])
    }
}

Erklärung:

Rezept K.14: Idempotente Cronjob-Abarbeitung mit Leases

Problem: Ein Hintergrund-Job zur Prüfung offener Mahnungen soll jede Nacht um 02:00 Uhr laufen. Mehrere Serverinstanzen dürfen den Job niemals doppelt ausführen.

Lösung:

schedule "0 2 * * *" {
    name: "nightly_payment_reminders"
    timeout: 3600

    execute uses Database, Clock {
        transaction {
            let pending_invoices = query(
                "SELECT id, customer_mail, due_date FROM invoices WHERE status = 'open' AND due_date < CURRENT_DATE() FOR UPDATE SKIP LOCKED",
                []
            )
            for inv in pending_invoices {
                execute("UPDATE invoices SET status = 'reminded' WHERE id = ?", [inv.id])
            }
        }
    }
}

Erklärung:

Rezept K.15: Streaming-CSV-Export für DATEV / Buchhaltung

Problem: Für den Steuerberater müssen hunderttausende Buchungssätze in ein normiertes CSV-Format exportiert werden, ohne dass der Arbeitsspeicher des Webservers überläuft.

Lösung:

fn export_datev_csv(t_id: TenantId, year: Int) -> String uses Database {
    mutable csv_output = "Datum;Beleg;Konto;Gegenkonto;Betrag;Text\n"
    let entries = query(
        "SELECT booking_date, voucher_no, account, contra_account, amount, notice FROM bookings WHERE tenant_id = ? AND fiscal_year = ? ORDER BY booking_date ASC",
        [t_id, year]
    )
    for row in entries {
        csv_output = csv_output + row.booking_date.to_string() + ";" + row.voucher_no + ";" + row.account.to_string() + ";" + row.contra_account.to_string() + ";" + row.amount.to_string() + ";" + row.notice + "\n"
    }
    return csv_output
}

Erklärung: