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

Design — Phase 2: Bytecode und VM

Context

Motivation siehe proposal.md („Why"). Ausgangslage: tb-frontend liefert AST + Diagnosen, wirft aber alle Sema-Ergebnisse (Typen, Slots, Konstanten) weg; tb-vm ist ein Stub. Rahmenbedingungen aus PLAN.md und docs/tbvm-design.md: Instant-Compile (Single-Pass, keine Optimierungspasses), Interpreter-Tempo in Lua-Klasse, Werte-Modell als Tagged Enum mit Rc (kein GC — der Dialekt kennt keine Zyklen), step()-basierte, unterbrechbare VM. Entscheidungen dieses Dokuments wurden am 2026-09-02 in einer Explore-Session getroffen und bestätigt.

Goals / Non-Goals

Goals:

• Durchgängige Pipeline Quelltext → HIR → Bytecode → Ausführung mit byte-genauer Korpus-Ausgabe.
• Debugger-taugliche VM-Architektur, ohne dass der Debugger selbst (Phase 5) schon gebaut wird.
• Builtin-ABI, die Phase 3 nur noch „auffüllt".

Non-Goals:

• Mehrmodul-Linking und COMMON-Verknüpfung über Moduleinheiten (die Prozedurtabelle ist modul-qualifiziert angelegt, verknüpft wird ab Phase 5 mit .MAK-Projekten).
• Datei-E/A, Ereigniszustellung (Hooks über Tick-Flag-Wort genügen), tbc build --exe, Optimierungspasses jeder Art.

Decisions

D1 — Typisiertes HIR als Sema-Ausgabe (statt Doppel-Resolution oder Side-Tables)

Die Sema wird vom reinen Checker zum Lowering-Pass: Ausgabe ist ein eigener HIR-Baum (Namen → Slots, Typen an jedem Ausdruck, Konstanten gefaltet, implizite Konvertierungen als explizite Knoten). Verworfen: (a) Codegen resolved selbst nochmal — dupliziert die Typisierungslogik, Divergenz-Bugs; (b) Side-Tables am AST — der AST hat keine Node-IDs, Pointer-Keys sind fragil. Das HIR hält das Single-Pass-Budget ein (alle Pässe linear, keine globale Analyse) und macht den Codegen zum dummen Tree-Walk.

D2 — Monomorpher Opcode-Satz, Konvertierungen als eigene Opcodes

Da das HIR jede Konvertierung materialisiert, sind alle Arithmetik-, Vergleichs- und Konvertierungs-Opcodes typrein (ADD_I16, ADD_F64, CONV_I16_F64, STR_EQ …). Kein Tag-Dispatch in heißen Pfaden; die Konvertierungsmatrix lebt an genau einer Stelle (HIR-Erzeugung), der Interpreter bleibt eine enge match-Schleife. Preis: breiter Opcode-Satz (~150–200) — Fleiß, keine Komplexität. Encoding: Opcode 1 Byte; Slots u16; Konstantenpool-Index u16 (Wide-Variante bei Bedarf); Sprünge u32-absolut innerhalb der Prozedur (fixup-freundlich).

D3 — Host-Trait mit blockierenden Aufrufen (statt Yield-Modell)

Alle Konsolenwirkungen laufen über ein Host-Trait (Ausgabe, Zeile lesen, Abbruchprüfung). Host-Calls dürfen blockieren und sind aus VM-Sicht atomar; Ticks (Breakpoints, Einzelschritt, Abbruch) greifen an Anweisungsgrenzen. Verworfen: VM „yieldet" bei E/A und der Einbetter erfüllt Requests — debuggerfreundlicher, aber deutlich komplexer; für den IDE-Debugger reicht die Anweisungsgranularität. Implementierungen: Konsolen-Host (tbc run), Capture-Host (Test-Harness), später Zellenpuffer-Host (Phase 3/5).

D4 — Fehlerbehandlung: Handler-Zustand modul-global + pro Frame

ON ERROR GOTO setzt den modulweiten Handler, ON LOCAL ERROR einen Frame-lokalen, der ihn verdeckt. Beim Fehler: aktiven Handler suchen (erst Frame-Kette nach LOCAL-Handlern, sonst Modul-Handler), Stack bis zum Handler-Frame abwickeln, gemerkten Anweisungs-Offset + Frame für RESUME sichern, ERR/ERL setzen. Fehler bei aktiver Behandlung → sofortiger Abbruch (keine Kaskade). Grundlage ist die Original-Hilfe (Topics ON ERROR, RESUME); ein Emulator-Spike ist nur nötig, falls die Doku Lücken lässt.

D5 — GOSUB-Stack pro Frame

GOSUB legt die Rücksprungadresse auf einen separaten Stack im aktuellen Frame (kein Call-Frame); RETURN bedient zuerst diesen Stack. Prozedurende mit nicht-leerem GOSUB-Stack verwirft ihn (wie beim Vorbild beim Verlassen der Prozedur).

D6 — Runner-Verhalten STOP/CONT

STOP außerhalb der IDE terminiert mit Meldung + Exit-Code ≠ 0; END/ Programmende → Exit-Code 0. CONT ist Direktmodus-Konzept der IDE (Phase 5) — die step()-Architektur liefert Suspend/Resume dort gratis.

D7 — .tbc mit eigenem Writer/Reader (kein serde)

Format bleibt stabil, dokumentiert und unabhängig von Crate-Versionen; Abschnittstabelle erlaubt spätere Abschnitte (FORMS ab Phase 4) ohne Versionsbruch. Prozedurtabelle trägt von Beginn an die Modulkennung.

D8 — Benchmarks als früher Bestandteil, nicht als Abschluss

Das Compile-Budget-Harness (generiertes ~50k-Zeilen-Projekt) entsteht früh in der Phase, damit Architekturfehler (z. B. quadratische Fixup-Listen) sofort auffallen. Criterion-Benches für VM-Durchsatz (Schleifen/Strings); Ergebnisse werden in docs/tbvm-design.md festgehalten. Ein Dispatch-Mikrobenchmark vorab wurde verworfen (vorzeitige Optimierung — gemessen wird am echten Interpreter).

Risks / Trade-offs

• [Sema-Umbau destabilisiert Phase-1-Ergebnis] → Diagnostik-Verhalten ist durch die 33 Frontend-Tests + Korpus fixiert; Umbau gilt erst als fertig, wenn alle Bestandstests grün sind.
• [Opcode-Breite macht Interpreter-Match unübersichtlich] → Opcodes systematisch gruppieren (Makro/Tabelle generiert Emit + Dispatch konsistent); Dokumentationspflicht in tbvm-design.md.
• [Konvertierungsmatrix enthält falsch rekonstruierte Zellen] → jede Zelle mit Fundstelle in der Original-Hilfe belegen; unklare Zellen als TODO verify im Korpus markieren (Konvention besteht).
• [PRINT-Zahlformatierung (SINGLE/DOUBLE-Stellen) weicht ab] → byte-genaue Korpustests decken Randfälle ab; Formatierungsregeln aus der Original-Hilfe ableiten, Abweichungen dokumentieren.
• [Blockierende Host-Calls verhindern Abbruch während INPUT] → akzeptiert für Phase 2 (Abbruchprüfung obliegt dem Host); die Ereignisschleifen-Architektur (Phase 4) kann den Host asynchroner gestalten, ohne die VM zu ändern.

Migration Plan

Rein additiv (neue Crate-Inhalte, neue Sema-Ausgabe neben bestehender Diagnostik). Kein Rollback-Plan nötig; PLAN.md-Haken und docs/tbvm-design.md-Fortschreibung erfolgen beim Abschluss der Phase.

Open Questions

• Exakte Ergebnistyp-Regel für ^ sowie Stellenzahl der SINGLE/DOUBLE-Textdarstellung: wird beim Ausformulieren der Matrix aus der Original-Hilfe übernommen; ändert weder Ansatz noch Task-Zuschnitt.
• Ob ERL beim Vorbild auch Zeilennummern aus GOSUB-Zielen o. ä. Sonderfällen meldet: bei Doku-Lücke entscheidet ein kurzer Emulator-Check; betrifft nur eine Matrix-/Handlerzelle.