Phase 4: Ereignisschleife und klassische Traps

openspec/changes/archive/2026-09-04-phase-4-ereignisschleife/proposal.md

@@ -0,0 +1,125 @@
+# Phase 4 (Eingang) — Ereignisschleife und klassische Ereignis-Traps
+
+## Why
+
+Phase 4 beginnt laut PLAN mit der Ereignisschleifen-Architektur. Diese
+Architektur lässt sich an den **klassischen Ereignis-Traps** vollständig
+bauen und beweisen, ohne eine Zeile Forms-Objektmodell: Sie brauchen
+dieselbe Warteschlange, dieselben Zustellpunkte, dieselbe Maskierung und
+denselben Rückruf in die VM, aber keine Formulare, keine Steuerelemente
+und kein `.FRM`. Umgekehrt müsste der Entwurf der Schleife mitten im
+Objektmodell blind bezahlt werden.
+
+Phase 3 hat die halbe Maschinerie bereits nebenbei gebaut: die
+`Ereignis`-Warteschlange, das Einsortieren in `RtState::pump`, die
+Zustellpunkte an Anweisungsgrenzen und vor blockierender Eingabe sowie
+den `CaptureHost` für Tests ohne Terminal. Es fehlen drei Dinge: eine
+**Zeitquelle**, die **Maskierung** einzelner Ereignisquellen und vor
+allem der **Rückruf in die VM** — heute gibt es keinen Weg, aus der
+Laufzeit heraus eine Prozedur oder ein `GOSUB`-Ziel des laufenden
+Programms auszuführen. `DOEVENTS()` liefert deshalb konstant 0.
+
+Zugleich sind die zehn Ereignis-Elemente die letzte Lücke des Inventars
+außerhalb von Forms: von den 15 offenen Einträgen entfallen zehn auf
+diese Gruppe, drei auf die Forms-Dialoge und zwei auf Phase 5.
+
+## What Changes
+
+- **Ereignisquellen und Warteschlange**: Das Ereignismodell der Laufzeit
+  wird um eine **Zeitquelle** erweitert. Die Zeit kommt vom Host, nicht
+  aus einem direkten Uhrzugriff der Laufzeit — nur so kann der
+  `CaptureHost` virtuelle Zeit stellen und ein Korpusprogramm mit
+  `ON TIMER` deterministisch prüfen. **BREAKING** für den `Host`-Trait.
+- **Mausereignisse als vierte Quelle**: Der `TerminalHost` verwirft die
+  Mausereignisse von `crossterm` heute. Sie werden aufgenommen und in
+  Zellenkoordinaten geführt — Tastendruck, Loslassen und Bewegung mit
+  Taste und Umschaltzustand. Die Eingangsaufgabe der Phase lautet
+  „Terminal-Events → Event-Queue → VM-Ticks"; die Maus ist ein
+  Terminal-Event und damit Teil der Schleife, auch wenn sie erst die
+  Steuerelemente auswerten.
+- **Rückruf in die VM**: Ereigniszustellung wird ein Vorgang der VM, kein
+  Builtin. Ein zugestelltes Ereignis führt das `GOSUB`-Ziel seines Traps
+  aus und kehrt danach an die unterbrochene Stelle zurück. Damit
+  bekommt auch `DOEVENTS()` seine Wirkung.
+- **Zustellpunkte**: Die vorhandenen Punkte (Anweisungsgrenze,
+  blockierende Eingabe) werden zu einer geschlossenen, dokumentierten
+  Liste ausgebaut: Anweisungsgrenze, `DOEVENTS`, `SLEEP` (wird durch ein
+  zugestelltes Ereignis beendet) und blockierende Eingabe. Zwischen
+  Zustellpunkten unterbricht nichts das Programm.
+- **Klassische Ereignis-Traps** (Sprachreferenz §8, **10
+  Inventareinträge**): `ON TIMER(n&)`, `ON KEY(n%)`, `ON UEVENT` und
+  `ON SIGNAL(n%)` je mit `GOSUB label`; die Steueranweisungen `TIMER`,
+  `KEY(n)`, `UEVENT` und `SIGNAL(n)` je mit `ON`/`OFF`/`STOP` sowie die
+  Klammer `EVENT` mit `ON`/`OFF`; dazu `SetUEvent`. Wertebereiche nach
+  Beleg: `KEY` 0, 1–25, 30–31; `TIMER` 1–86 400 Sekunden; `SIGNAL` 1–2.
+  Ihr Status im Inventar wechselt
+  auf `implementiert`.
+- **Maskierung mit drei Zuständen**: `ON` stellt zu, `OFF` verwirft —
+  auch ein unter `STOP` bereits gemerktes Ereignis —, `STOP` merkt eines
+  und stellt es beim nächsten `ON` zu. Der Eintritt in einen Handler
+  führt selbsttätig `STOP` seiner Quelle aus, das `RETURN` selbsttätig
+  `ON`, außer im Handler stand ein ausdrückliches `OFF`.
+- **`SIGNAL` auf Betriebssystemsignale** (Entscheidung 2026-09-04): Die
+  Quelle des Vorbilds war OS/2-gebunden (Prozessflags über
+  `DOSFLAGPROCESS`) und existiert nicht. Abgebildet wird die minimale
+  Menge, die auf allen Zielplattformen besteht: `SIGNAL(1)` auf `SIGINT`,
+  `SIGNAL(2)` auf `SIGTERM`. Signale erreichen die Laufzeit über den
+  Host, nicht im Signalkontext.
+- **Getrappte Tasten verlassen den Eingabestrom**: Eine Taste, für die
+  ein aktiver `ON KEY`-Trap besteht, wird zugestellt und MUST NOT
+  zusätzlich bei `INKEY$`, `INPUT` oder `INPUT$` erscheinen.
+- **Namentliche Abweisung im Frontend**: Die zehn Elemente erhalten
+  Grammatik und Signaturen. Heute rutscht `ON TIMER(5) GOSUB marke`
+  stillschweigend in das berechnete `ON ausdruck GOSUB` — genau der
+  Fall, den der Guiding Principle als Bug definiert.
+
+**Non-Goals:**
+
+- Die **Auswertung** von Mausereignissen durch Steuerelemente
+  (Trefferprüfung, Fokuswechsel, Ziehen) — sie setzt das Objektmodell
+  voraus und gehört zum Change der Steuerelemente. Quelle,
+  Warteschlange und Koordinatenmodell entstehen hier.
+- Das Forms-Objektmodell, Steuerelemente, `.FRM` und die Dialoge
+  (`MSGBOX`, `INPUTBOX$`) — eigene Changes derselben Phase.
+- `COM`, `PEN`, `PLAY`, `STRIG` bleiben Non-Feature (Fehler 73).
+
+## Capabilities
+
+### New Capabilities
+
+- `ereignissteuerung`: Ereignisquellen (Tastatur, Zeit,
+  benutzerdefiniert), Warteschlange und Reihenfolge, Zustellpunkte,
+  Maskierung mit `ON`/`OFF`/`STOP` je Quelle und global, Zustellung als
+  `GOSUB` in das laufende Programm, Zusammenspiel mit Fehlerbehandlung
+  und blockierender Eingabe.
+
+### Modified Capabilities
+
+- `sprach-frontend`: Grammatik und Signaturprüfung SHALL die
+  Trap-Anweisungen und `SetUEvent` umfassen; `ON <quelle>(n) GOSUB`
+  MUST NOT als berechnetes `ON ausdruck GOSUB` behandelt werden.
+- `vm-ausfuehrung`: Die VM SHALL an Anweisungsgrenzen anstehende
+  Ereignisse zustellen und dafür das `GOSUB`-Ziel des Traps ausführen,
+  ohne den unterbrochenen Zustand zu verlieren.
+- `kompat-testkorpus`: Korpusabdeckung der Ereignis-Traps mit
+  deterministischer Zeit.
+
+## Impact
+
+- `crates/tb-runtime`: `Ereignis` und der `Host`-Trait um die Zeitquelle
+  erweitert (**BREAKING**); Trap-Zustände und Warteschlange in `RtState`;
+  `INKEY$`-Puffer filtert getrappte Tasten; `SLEEP` endet bei Zustellung.
+- `crates/tb-vm`: Zustellung als Vorgang der Ausführung (neue
+  Instruktion und Frame-Behandlung); `DOEVENTS` erhält Wirkung.
+- `crates/tb-frontend`: Grammatik und Signaturen der zehn Elemente;
+  `Unsupported`-Absenkung von `SETUEVENT` entfällt.
+- `crates/tb-ui`: `TerminalHost` liefert die Zeit, reicht die
+  Mausereignisse von `crossterm` durch, statt sie zu verwerfen, und
+  meldet Betriebssystemsignale als Ereignis.
+- `tests/compat`: neue Korpusprogramme für Zeit-, Tasten- und
+  UEvent-Traps sowie für `ON`/`OFF`/`STOP`.
+- `docs/`: `sprachreferenz.md` §8 ausformuliert; `inventar.md` setzt die
+  zehn Einträge auf `implementiert`; `bibliothek.md` um die Elemente
+  erweitert.
+- PLAN.md: die Eingangsaufgabe von Phase 4 und der Punkt „Klassische
+  Ereignis-Traps" sind damit erledigt.