TerminalBasic/openspec/changes/archive/2026-09-02-phase-2-bytecode-vm/tasks.md

Tasks — Phase 2: Bytecode und VM

1. Feindesign-Dokumentation (Eingangsaufgabe aus Phase 0)

• 1.1 Zahlenkonvertierungs-Matrix (implizite Casts, Banker's Rounding, Überlauf, / vs. \/MOD, logische Operatoren, CURRENCY, ^-Regel, SINGLE/DOUBLE-Textdarstellung) als Tabelle in docs/tbvm-design.md schreiben; jede Zelle mit Fundstelle in der Original-Hilfe belegen, unklare Zellen als TODO verify markieren — verifizierbar: Abschnitt existiert, keine Zelle ohne Beleg oder TODO-Marke
• 1.2 Opcode-Satz vollständig in docs/tbvm-design.md ausformulieren (Gruppen, Encoding, Operanden) und STOP/CONT-Runner-Entscheidung sowie Fehlerbehandlungs-Scoping (design.md D4–D6) dort festhalten — verifizierbar: „Offene Punkte"-Abschnitt in tbvm-design.md ist leer

2. Frontend: Typisiertes HIR

• 2.1 HIR-Datenmodell in tb-frontend definieren (Slots, typisierte Ausdrücke, explizite Konvertierungsknoten, Prozedur-/Modulstruktur, Quellzeilen-Anker) — verifizierbar: cargo check und Doku-Kommentare je Knotentyp
• 2.2 Sema zum Lowering-Pass umbauen: analyze_source liefert zusätzlich HIR; Konstantenfaltung, DEFtype, implizite Konvertierungen materialisieren — verifizierbar: alle 33 bestehenden Frontend-Tests bleiben grün
• 2.3 HIR-Tests: diagnose-freie Korpusmodule liefern vollständiges HIR; Konvertierungsknoten-Szenario (d# = i% + 1.5) als Unit-Test — verifizierbar: neue Tests in crates/tb-frontend/tests grün

3. Bytecode und Serialisierung

• 3.1 Opcode-Definitionen und Modulstruktur (Konstantenpool, Typtabelle, modul-qualifizierte Prozedurtabelle, DATA-Segment, Zeilentabelle) in tb-vm::bytecode implementieren — verifizierbar: Unit-Tests für Encoding/Decoding einzelner Opcodes
• 3.2 .tbc-Writer/Reader (Magic, Formatversion, Abschnittstabelle) implementieren — verifizierbar: Roundtrip-Test (schreiben → laden → identisch) und Ablehnungstest für unbekannte Formatversion

4. Codegenerator

• 4.1 Ausdrucks-Codegen (Literale, Slots, Arithmetik, Vergleiche, logische Operatoren, Konvertierungsknoten, String-Konkatenation) — verifizierbar: Unit-Tests HIR-Ausdruck → erwartete Opcode-Folge
• 4.2 Kontrollfluss-Codegen (IF, SELECT CASE, FOR, DO, WHILE, GOTO/GOSUB/ON GOTO, EXIT, Labels/Zeilennummern) mit Fixup-Listen für Vorwärtsziele — verifizierbar: Unit-Tests je Konstrukt
• 4.3 Prozedur-Codegen (SUB/FUNCTION/DEF FN, BYREF-/BYVAL-Argumente, STATIC, Frames/Locals), DIM/Arrays/UDTs, DATA-Segment und Zeilentabelle emittieren — verifizierbar: Unit-Tests und cargo test -p tb-vm grün

5. Interpreter (TBVM)

• 5.1 VM-Grundgerüst: Werte-Modell, Operandenstack, Frames, step()-Schleife mit Tick-Flag-Wort an Anweisungsgrenzen — verifizierbar: Ausdrucks-Programme laufen in Unit-Tests
• 5.2 Kontrollfluss und GOSUB-Stack pro Frame inkl. Fehler 3 („RETURN without GOSUB") — verifizierbar: kontrollfluss.bas läuft im Capture-Host mit korrekter Ausgabe
• 5.3 Prozeduraufrufe (BYREF-Rückwirkung, Klammer-BYVAL, STATIC, Rekursion, DEF FN im Modulkontext) — verifizierbar: Unit-Tests der Spec-Szenarien aus vm-ausfuehrung
• 5.4 DATA/READ/RESTORE inkl. Fehler 4 und 13 — verifizierbar: Unit-Tests der Spec-Szenarien
• 5.5 Fehlerbehandlung: Handler-Zustand (modul-global + Frame-lokal), Unwinding, RESUME-Varianten, ERR/ERL, ERROR n, Fehler im Handler fatal — verifizierbar: alle Szenarien aus vm-fehlerbehandlung als Tests grün
• 5.6 Unterbrechbarkeit: Breakpoints auf (Modul, Zeile), Einzelschritt, Variableninspektion im Halt, Abbruchwunsch — verifizierbar: Unit-Tests treiben die VM per step() und prüfen Halt/Inspektion
• 5.7 Programmende: END/SYSTEM/Programmende vs. STOP mit Meldung und Exit-Code-Unterscheidung — verifizierbar: Runner-Test prüft Exit-Codes und Meldung

6. Konsolen-Basisbibliothek (tb-runtime-Scheibe)

• 6.1 Host-Trait definieren; Konsolen-Host und Capture-Host implementieren — verifizierbar: Unit-Test zeichnet Ausgabe byte-genau auf
• 6.2 Builtin-Dispatch-Tabelle + CALL_BUILTIN-ABI (Argumente auf dem Stack) in VM und Runtime verdrahten — verifizierbar: LEN-Aufruf läuft über die Tabelle (Spec-Szenario)
• 6.3 PRINT-Formatierung: Zahlendarstellung je Typ, Vorzeichenspalte, nachgestelltes Leerzeichen, ;/,-Semantik, 14-Zeichen-Druckzonen — verifizierbar: printzahlen.bas und printzonen.bas byte-genau korrekt
• 6.4 Korpus-Stringfunktionen (LEN, LEFT$, RIGHT$, MID$, INSTR, UCASE$, LCASE$, STRING$, SPACE$, CHR$, ASC, STR$, VAL) mit Randfällen des Vorbilds — verifizierbar: strings.bas byte-genau korrekt plus Randfall-Unit-Tests (VAL-Präfixlesen, STR$-Leerzeichen, ASC("") → Fehler 5)

7. CLI und Test-Harness

• 7.1 tbc run <datei.bas>: kompilieren, .tbc in Memory ausführen, Konsolen-Host; Diagnosen bei Compile-Fehler, Exit-Codes nach D6 — verifizierbar: tbc run tests/compat/hello.bas druckt Hallo, Welt!
• 7.2 Harness in tests/: alle tests/compat/*.bas kompilieren, im Capture-Host ausführen, byte-genau gegen .out vergleichen; bei Abweichung Datei/Zeile/Soll/Ist nennen — verifizierbar: cargo test führt den kompletten Korpus aus
• 7.3 Korpus erweitern: Konvertierungsmatrix-Programm, Fehlerbehandlung (ON ERROR/RESUME/ERR/ERL), BYREF/BYVAL-Programm mit dokumentierter Sollausgabe (Belege bzw. TODO verify-Konvention) — verifizierbar: neue .bas/.out-Paare laufen im Harness grün

8. Benchmarks und Abschluss

• 8.1 Compile-Budget-Harness früh aufsetzen: Generator für ~50k-Zeilen-Projekt + Criterion-Bench; Budgetvergleich (< 1 s Projekt, < 50 ms Modul) — verifizierbar: cargo bench weist die Zeiten aus
• 8.2 VM-Durchsatz-Benches (Schleifen, Strings); Ergebnisse und Benchmark-Stand in docs/tbvm-design.md „Performance" festhalten — verifizierbar: Abschnitt enthält Messwerte mit Datum
• 8.3 Meilenstein-Verifikation und Doku-Abschluss: kompletter Korpus grün via cargo test, docs/sprachreferenz.md um Phase-2-Festlegungen ergänzt (Rundung, STOP-Verhalten), PLAN.md-Phase-2-Haken gesetzt — verifizierbar: alle Checkboxen der Phase in PLAN.md abgehakt, Testsuite grün