# Phase 2 — Bytecode und VM (`tb-vm`)

## Why

Das Sprach-Frontend (Phase 1) liefert einen typgeprüften AST, aber es gibt
keine Ausführungsschicht: `tb-vm` besteht aus leeren Stub-Modulen, der
Kompatibilitäts-Testkorpus ist nur eine ruhende Verhaltensspezifikation.
Phase 2 macht aus dem Frontend einen Compiler mit lauffähigem Ergebnis —
Bytecode-Erzeugung, serialisierbares Kompilat (`.tbc`) und die TBVM als
Interpreter — und löst damit den Plan-Meilenstein ein: der Konsolen-Korpus
läuft per `tbc run` mit byte-genau korrekter Ausgabe.

## What Changes

- **Typisiertes HIR als Sema-Ausgabe** (Entscheidung 2026-09-02, Explore-
  Session): Die semantische Analyse behält ihr Wissen — sie liefert neben
  Diagnostics einen abgesenkten, typisierten Zwischenbaum (Namen → Slots,
  Typen explizit, Konstanten gefaltet, implizite Konvertierungen als
  explizite Knoten). Der Codegen wird ein einfacher Tree-Walk.
- **Bytecode-Feindesign** (Eingangsaufgabe aus Phase 0): monomorpher,
  typisierter Opcode-Satz; Zahlenkonvertierungs-Matrix (implizite Casts,
  Banker's Rounding, Überlauf → Fehler 6) als Tabelle in
  docs/tbvm-design.md und als Korpustest verankert.
- **`.tbc`-Container**: Serialisierung mit eigenem Writer/Reader (Magic,
  Formatversion, Abschnittstabelle: CONSTS, TYPES, PROCS, CODE, DATA,
  LINES); Prozedurtabelle von Beginn an modul-qualifiziert.
- **TBVM-Interpreter**: Ausdrücke, Kontrollfluss (`IF`, `SELECT CASE`,
  Schleifen, `GOTO`/`GOSUB`), Prozeduraufrufe mit BYREF-Semantik,
  `DEF FN`, `DATA`/`READ`/`RESTORE`.
- **Fehlerbehandlung**: `ON ERROR GOTO` (modulweit), `ON LOCAL ERROR`
  (prozedurlokal), `RESUME [0|NEXT|label]`, `ERR`/`ERL`, Propagation die
  Aufrufkette hoch, Fehler im Handler fatal.
- **Unterbrechbarkeit**: `step()`-basierte VM, Tick-Prüfung an
  Anweisungsgrenzen (ein Flag-Wort), Breakpoints, Einzelschritt,
  Variableninspektion — Grundlage für den IDE-Debugger (Phase 5).
- **Runner-Verhalten** (Entscheidung 2026-09-02): `STOP` außerhalb der IDE
  terminiert mit Meldung und Exit-Code ≠ 0, `END` mit Exit-Code 0;
  `CONT` bleibt IDE-Konzept (Phase 5).
- **Konsolen-Basisbibliothek (vorgezogene Phase-3-Scheibe)**: Builtin-ABI
  (Dispatch-Tabelle in `tb-runtime`), `Host`-Trait für Konsolen-E/A
  (blockierende Host-Calls, kein Yield-Modell), PRINT-Zahlenformatierung
  und Druckzonen sowie die vom Korpus benötigten Stringfunktionen.
- **Test-Harness**: `cargo test` führt jede Korpusdatei per `tbc run` aus
  und vergleicht byte-genau gegen `.out`.
- **Benchmarks** in `benches/`: Compile-Budget (~50k Zeilen < 1 s, Modul
  < 50 ms) und VM-Durchsatz; Ergebnisse in docs/tbvm-design.md.

**Non-Goals:** Mehrmodul-Linking/`COMMON`-Verknüpfung über Moduleinheiten
(kommt mit Projekten, Phase 5); Datei-E/A, Ereignissteuerung, `tbc build
--exe` (spätere Phasen); vollständige Standardbibliothek (Phase 3).

## Capabilities

### New Capabilities

- `bytecode-kompilat`: Codegen HIR → Bytecode, Opcode-Satz,
  `.tbc`-Format und Serialisierung, Instant-Compile-Budget.
- `vm-ausfuehrung`: Interpreter-Semantik — Ausdrücke inkl.
  Zahlenkonvertierungs-Matrix, Kontrollfluss, Prozeduraufrufe/BYREF,
  `GOSUB`, `DEF FN`, `DATA`/`READ`, Runner-Verhalten (`STOP`/`END`) und
  Unterbrechbarkeit (Ticks, Breakpoints, Einzelschritt).
- `vm-fehlerbehandlung`: `ON [LOCAL] ERROR`, `RESUME`, `ERR`/`ERL`,
  Handler-Scoping und Fehlerpropagation.
- `konsolen-basisbibliothek`: `Host`-Trait, Builtin-ABI,
  PRINT-Formatierung/Druckzonen, Korpus-Stringfunktionen.

### Modified Capabilities

- `sprach-frontend`: Die Sema SHALL zusätzlich zum Diagnostik-Ergebnis
  ein typisiertes HIR liefern (neue Ausgabe-Anforderung des Frontends).
- `kompat-testkorpus`: Neuer Laufzeitvergleich — jede Korpusdatei läuft
  per `tbc run`, Ausgabe wird byte-genau gegen `.out` geprüft.

## Impact

- `crates/tb-frontend`: Sema-Umbau (HIR-Ausgabe), neues HIR-Modul.
- `crates/tb-vm`: `bytecode.rs`, `codegen.rs`, `interp.rs` von Stub zu
  Vollimplementierung; neue Benchmarks.
- `crates/tb-runtime`: Builtin-Dispatch-Tabelle, PRINT-Formatierung,
  Stringfunktionen (Scheibe).
- `crates/tb-cli`: `tbc run` (Kompilieren + Ausführen), Konsolen-`Host`.
- `tests/compat`: Harness + neue Korpusdateien (u. a. Konvertierungs-
  matrix, Fehlerbehandlung); `docs/tbvm-design.md` wird fortgeschrieben
  (Opcode-Satz, Matrix, Benchmark-Ergebnisse), PLAN.md-Haken folgen bei
  Abschluss.