TerminalBasic/openspec/changes/phase-3-runtime-bildschirm/proposal.md

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.