# Phase 3 (Kern) — Laufzeitbibliothek, Bildschirm und Datei-E/A ## Why Phase 2 hat eine lauffähige VM geliefert, aber nur eine dünne Bibliotheksscheibe: rund 50 dokumentierte Anweisungen und Funktionen sind im Frontend zwar typgeprüft, senken aber auf `HStmtKind::Unsupported`/ `HExpr::Unsupported` ab und enden zur Laufzeit in Fehler 73. Betroffen sind alle Bildschirmanweisungen (`CLS`, `LOCATE`, `COLOR`, `VIEW PRINT`, `CSRLIN`, `POS`, `INKEY$`), die komplette Datei-E/A, `PRINT USING`, die Datums-/Zeitfunktionen und die System-Anweisungen. Klassische Konsolenprogramme des Vorbilds laufen damit nicht. Zusätzlich fehlt das Messinstrument: die Leitplanke „Vollständigkeit ist das Soll" fordert ein Inventar aller Anweisungen/Funktionen mit Abdeckungsstatus als Abnahmekriterium für Phase 6 — bislang existiert nur die Implementierungsseite (die `Unsupported`-Marker), nicht die Sollseite aus der Original-Hilfe. Dieser Change löst den Plan-Meilenstein „klassische Konsolenprogramme laufen unverändert" ein. ISAM ist als eigener Change `phase-3-isam` ausgegliedert und schließt Phase 3 ab. ## What Changes - **Vollständigkeits-Inventar** (`docs/inventar.md`): Tabelle aller Anweisungen, Funktionen und Metabefehle des Vorbilds aus der Original-Hilfe mit Status `implementiert` / `offen` / `Non-Feature` und Fundstelle. Ein automatischer Test gleicht die Tabelle gegen `builtin_fn`/`builtin_stmt` und die `Unsupported`-Marker im Code ab; Divergenz schlägt fehl. Damit misst sich die Abdeckung selbst. - **Bildschirmpuffer wandert nach `tb-runtime`** (Entscheidung 2026-09-03, Explore-Session): `Cell`/`TextScreen` mit der kompletten Bildschirmsemantik (Cursor, Farbattribute, Scrollen, `VIEW PRINT`, `resize`) ziehen ratatui-frei von `tb-ui::screen` nach `tb-runtime::screen`. In `tb-ui` bleiben nur die Ratatui-Anbindung (`basic_color`, `impl Widget`) und künftig der Terminal-Adapter. Begründung: `PRINT`, `LOCATE`, `CLS` und `SCREEN()` sind Elemente der Laufzeitbibliothek und müssen den Puffer erreichen; zugleich bleiben `tb-vm` und `tb-runtime` damit frei von einer Terminal-Abhängigkeit, sodass jedes Bildschirmverhalten ohne Terminal prüfbar ist. Die Forms-Engine bleibt laut PLAN.md in `tb-ui::forms` (Entscheidung 2026-09-03) und zeichnet von dort in denselben Puffer — `tb-ui` hängt künftig an `tb-runtime`, nicht umgekehrt. - **BREAKING: `Host`-Trait neu geschnitten**: statt `write(&str)` / `read_line()` künftig Präsentation eines Zellenpuffers und Ereignisabfrage. `write`/`read_line` können den Bildschirmzustand nicht transportieren (`LOCATE`, `COLOR`, `CSRLIN`, `SCREEN(r,c)` liest vom Bildschirm zurück). Betrifft `ConsoleHost`, `CaptureHost` und `tbc run`. - **BREAKING: Korpusvergleich auf Bildschirm-Snapshot** (getrimmt): `.out`-Dateien halten künftig das Textbild des Puffers bis zur letzten belegten Zelle statt eines Byte-Streams; eine Attributebene kommt nur hinzu, wenn das Programm `COLOR` verwendet. Die acht bestehenden Golden Files werden neu erzeugt. Ein Byte-Stream kann `LOCATE`/`COLOR` nicht abbilden. - **Bildschirmanweisungen und -funktionen**: `CLS`, `COLOR`, `LOCATE`, `WIDTH`, `SCREEN` (Anweisung und Funktion), `VIEW PRINT`, `CSRLIN`, `POS`, `INKEY$`, `INPUT$`, `TAB`, `SPC`, `KEY` (inkl. Klärung des Umfangs der Funktionstasten-Makros `KEY LIST`/`ON`/`OFF`). - **80×25 ist nirgends eine feste Grenze** (Vorgabe des Projektinhabers 2026-09-03, Priorität für das ganze Programm): 80×25 steht stets als Synonym für „voller Bildschirm". Kein beobachtbares Verhalten darf eine feste Spalten- oder Zeilenzahl voraussetzen — `CLS`, der voreingestellte Scrollbereich, Umbruch- und Scrollgrenzen sowie die Bereichsprüfungen von `LOCATE` und `SCREEN()` folgen den aktuellen Abmessungen. Größenänderungen während der Ausführung werden als Ereignis zugestellt und angepasst (Inhalt oben links erhalten, Cursor und `VIEW PRINT`-Bereich geklemmt). Das Mindestmaß 80×25 bleibt ausschließlich eine untere Schranke der Darstellung. - **Breite Unicode-Zeichen belegen zwei Zellen** (Entscheidung 2026-09-02): Zellenmodell, Cursorfortschritt, `POS`/`LOCATE` und Umbruch am rechten Rand berücksichtigen die Darstellungsbreite (unicode-width). Ersetzt die bisherige Regel „1 Zeichen = 1 Zelle". - **Vollständige String- und Zahlenbibliothek**: die restlichen dokumentierten Stringfunktionen sowie `PRINT USING` und `FORMAT$` vollständig, inklusive Klärung des `%`-Präfixes bei Feldüberlauf. - **Datums- und Zeitfunktionen**: `NOW`, `DATESERIAL`, `TIMESERIAL`, `DATEVALUE`, `TIMEVALUE`, `DAY`, `MONTH`, `YEAR`, `WEEKDAY`, `HOUR`, `MINUTE`, `SECOND` sowie `DATE$`/`TIME$` als Anweisungsform. - **Finanzmathematik** (Befund aus Aufgabe 1.1, 2026-09-03 — im ursprünglichen Umfang übersehen): `FV#`, `PV#`, `Pmt#`, `IPmt#`, `PPmt#`, `NPer#`, `Rate#`, `NPV#`, `IRR#`, `MIRR#`, `SLN#`, `SYD#`, `DDB#`. - **Record-Konvertierungsfunktionen** (ebenfalls Befund 1.1): `MKI$`/`MKL$`/`MKS$`/`MKD$`/`MKC$` und `CVI`/`CVL`/`CVS`/`CVD`/`CVC` sowie die MBF-Varianten `MKSMBF$`/`MKDMBF$`/`CVSMBF`/`CVDMBF` — sie gehören zum `FIELD`-basierten wahlfreien Zugriff. - **Weitere Befunde aus 1.1**: `CURDIR$`, `DIR$`, `CHDRIVE`, `SHELL` als Funktion, `LPOS`, `STACK` (Anweisung und Funktion), `SYSTEM`, `ERDEV`/`ERDEV$`, `SetFormatCC`. - **Signaturen für alle Inventarelemente**: Die Semantik führt für jedes im Inventar geführte Element eine Signatur, auch wenn das Laufzeitverhalten noch aussteht — sonst enden dokumentierte Elemente in „unbekannter Bezeichner" statt in einer namentlichen Ablehnung. - **Mathematik vervollständigen**: kompatibler `RND`/`RANDOMIZE`-PRNG (gleiche Zahlenfolge wie das Vorbild bei gleichem Startwert), Rundungsverhalten, Integer-Überlauf → Fehler 6. - **Datei-E/A**: `OPEN` in beiden Syntaxen (sequenziell, random, binär), `CLOSE`, `RESET`, `PRINT #`, `WRITE #`, `INPUT #`, `LINE INPUT #`, `GET`, `PUT`, `FIELD`, `LSET`, `RSET`, `SEEK` (Anweisung und Funktion), `EOF`, `LOF`, `LOC`, `FREEFILE`, `FILEATTR`, `LOCK`/ `UNLOCK`, `NAME … AS`, `LPRINT`. Feste Strings in Records als UTF-32 (Entscheidung 2026-09-02, 4 Bytes/Zeichen, feste Recordlänge). - **System-Anweisungen**: `FILES`, `KILL`, `CHDIR`, `MKDIR`, `RMDIR`, `SHELL`, `ENVIRON`/`ENVIRON$`, `CLEAR`, `FRE`, `TRON`/`TROFF`, plattformübergreifende Pfadsemantik. - **Drei Altlasten aus Phase 2**: - `ON ERROR GOTO`-Scoping: ein Handler-Label auf Modulebene ist auch aus Prozeduren heraus ansprechbar; heute wird nicht-lokales `ON ERROR` in einer Prozedur fälschlich wie `ON LOCAL ERROR` behandelt (`sema.rs`, `lower_stmt`/`OnError`). - DATA-Rohtext: unquotierte `DATA`-Elemente verlieren die Groß-/ Kleinschreibung, weil der Lexer Bezeichner normalisiert. - `TODO verify`-Zellen der Konvertierungsmatrix in `docs/tbvm-design.md` gegen die Original-Hilfe auflösen (CURRENCY-Promotion mit Gleitkomma, `^`-Ergebnistyp, Exponentialform-Schwellen, CURRENCY-Ausgabeformat). **Non-Goals:** ISAM (eigener Change `phase-3-isam`, schließt Phase 3 ab); Forms-Engine, Ereignisschleife und Ereignissteuerung (`TIMER/KEY(n) ON| OFF|STOP`, `ON SIGNAL`/`SIGNAL`, `SETUEVENT`, `MSGBOX`, `INPUTBOX$` — Phase 4); IDE und Debugger (Phase 5); `tbc build --exe` (Phase 6). Die Forms-Engine bleibt laut PLAN.md in `tb-ui::forms` (Entscheidung 2026-09-03); dieser Change schafft ihr mit dem Puffer in `tb-runtime` nur die Zeichenfläche. ## Capabilities ### New Capabilities - `datei-eio`: Dateiverwaltung und Datenübertragung — `OPEN`/`CLOSE`, die drei Zugriffsarten (sequenziell, random, binär), Record-Layout mit UTF-32-Festtextfeldern, `FIELD`/`LSET`/`RSET`, Positions- und Statusfunktionen (`EOF`/`LOF`/`LOC`/`SEEK`/`FREEFILE`/`FILEATTR`), Sperren, Dateisystem-Anweisungen und plattformübergreifende Pfadsemantik. - `sprachinventar`: das Vollständigkeits-Inventar als prüfbares Artefakt — Aufbau der Tabelle, Statusvokabular, Pflicht zur Vollständigkeit gegenüber der Original-Hilfe und der automatische Abgleich gegen den Code. ### Modified Capabilities - `textbildschirm`: Der Zellenpuffer SHALL in `tb-runtime` liegen und ratatui-frei sein; das Unicode-Zellenmodell wechselt von „1 Zeichen = 1 Zelle" auf Darstellungsbreite (breite Zeichen belegen zwei Zellen); neue Anforderung für die Bildschirmanweisungen des Dialekts auf dem Puffer. - `konsolen-basisbibliothek`: Der `Host`-Trait wechselt vom Stream- auf ein Bildschirmmodell (Präsentation + Ereignisabfrage); die Funktionsliste wird von der Korpusscheibe auf die vollständige String-, Zahlen-, Formatierungs- (`PRINT USING`) und Datums-/ Zeitbibliothek erweitert; `RND` erhält eine Kompatibilitätsanforderung. - `kompat-testkorpus`: Der Laufzeitvergleich wechselt vom Byte-Stream auf einen getrimmten Bildschirm-Snapshot; neue Abdeckungsanforderung für Bildschirm-, Formatierungs- und Datei-E/A-Semantik. - `sprach-frontend`: `ON ERROR GOTO` auf Modulebene SHALL aus Prozeduren heraus ansprechbar sein (bisher fälschlich lokal); unquotierte `DATA`-Elemente SHALL ihren Rohtext behalten. ## Impact - `crates/tb-ui`: `screen.rs` verliert Puffer und Semantik an `tb-runtime`; zurück bleiben `basic_color` und `impl Widget` als Adapter auf den Runtime-Puffer. Neue Abhängigkeit `tb-runtime` (bisher waren beide Blätter im Abhängigkeitsgraphen); `forms.rs` bleibt als Platzhalter für Phase 4 unberührt. - `crates/tb-runtime`: neues `screen`-Modul; `host.rs` neu geschnitten (**BREAKING**); `strings`, `format`, `math`, `datetime`, `fileio`, `builtins` von Stub/Scheibe auf Vollimplementierung; neue Abhängigkeit `unicode-width`. - `crates/tb-frontend`: rund 50 `Unsupported`-Marker weichen echter Absenkung; rund 30 bislang signaturlose Elemente (Finanzmathematik, `MK…$`/`CV…`, `CURDIR$`, `DIR$`, `CHDRIVE`, `LPOS`, `STACK`, `SYSTEM`, `ERDEV`/`ERDEV$`, `SetFormatCC`) erhalten Signaturen; `sema.rs` (`ON ERROR`-Scoping), `lexer.rs` (DATA-Rohtext). - `crates/tb-vm`: neue Builtin-Indizes; `Instr::Unsupported` bleibt für die verbleibenden Phase-4-Marker bestehen. - `crates/tb-cli`: `tbc run` auf den neuen `Host`; Harness auf Snapshot-Vergleich (**BREAKING** für die acht bestehenden `.out`). - `tests/compat`: acht Golden Files neu erzeugt, neue Korpusdateien für Bildschirm, `PRINT USING`, Datei-E/A, Datum/Zeit, breite Zeichen. - `docs/`: neu `docs/inventar.md` und `docs/bibliothek.md`; fortgeschrieben `docs/sprachreferenz.md` (Doppelzellen, `KEY n`, `PRINT USING`-Überlauf) und `docs/tbvm-design.md` (Konvertierungsmatrix). PLAN.md-Haken folgen bei Abschluss.