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

# 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.