Phase 2 abgeschlossen: Bytecode, TBVM, Runtime-Scheibe, tbc run

- Sema zum Lowering-Pass umgebaut: typisiertes HIR (Slots, explizite
  Konvertierungsknoten) als Codegen-Eingabe; BYREF verlangt exakten Typ
- Bytecode-Feindesign umgesetzt: monomorpher Opcode-Satz,
  .tbc-Container (Formatversion 1) mit eigenem Writer/Reader
- Codegenerator HIR -> Bytecode (Fixup-Listen, keine globalen Passes)
- TBVM-Interpreter: Kontrollfluss, GOSUB-Stack je Frame, BYREF/BYVAL,
  STATIC, DEF FN, DATA/READ/RESTORE, ON [LOCAL] ERROR/RESUME/ERR/ERL,
  Breakpoints/Einzelschritt/Inspektion, STOP fortsetzbar
- Runtime-Scheibe: Host-Trait (Konsole/Capture), Builtin-Tabelle,
  Konvertierungsmatrix, PRINT-Formatierung/Druckzonen, Stringfunktionen
- tbc run/build/check mit Exit-Codes nach Entscheidung D6
- Korpus-Harness (byte-genauer Vergleich) + 3 neue Korpusdateien
  (konvertierung, fehlerbehandlung, byref); 137 Tests gruen
- Benchmarks: Einzelmodul 1,2 ms / Projekt 49.760 Zeilen 124 ms
  (Budgets eingehalten), VM ~5 Mio Schleifeniterationen/s
- Doku fortgeschrieben (tbvm-design, sprachreferenz, PLAN);
  verlagerte Punkte als explizite Aufgaben in Phase 3
- OpenSpec-Change phase-2-bytecode-vm (27/27 Tasks)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

openspec/changes/phase-2-bytecode-vm/design.md

@@ -0,0 +1,129 @@
+# 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.