TerminalBasic/openspec/changes/phase-3-isam/proposal.md

# Phase 3 (Abschluss) — ISAM-Datenbankunterstützung

## Why

Die Leitplanke „Vollständigkeit ist das Soll" und die Entscheidung vom
2026-09-02 legen fest: ISAM wird implementiert, es ist kein Non-Feature.
Heute existiert davon nur eine Parser-Klausel — `OPEN … FOR ISAM typname
tabellenname AS #n` wird erkannt und auf den „nicht verfügbar"-Marker
abgesenkt. Die eigentlichen ISAM-Anweisungen und -Funktionen
(`CREATEINDEX`, `SETINDEX`, `INSERT`, `RETRIEVE`, `UPDATE`, `DELETE`, die
`MOVE`- und `SEEK`-Familien, die Transaktionsanweisungen) besitzen im
Frontend **keine Signatur**. Sie enden damit in „unbekannter Bezeichner"
bzw. einem generischen Syntaxfehler — genau der Fall, den der Guiding
Principle als Bug definiert: ein dokumentiertes Feature wird still und
ohne Namensnennung abgewiesen.

Die Laufzeitfehler 81–89 des ISAM-Bereichs sind bereits als
`tb_runtime::errors` implementiert und warten auf ihre Auslöser.

Dieser Change schließt Phase 3 ab. Der vorausgehende Change
`phase-3-runtime-bildschirm` liefert die Datei-E/A-Grundlage
(Dateitabelle, Recordpuffer, UTF-32-Festtextfelder), auf der ISAM
aufsetzt, sowie das Inventar, in dem die ISAM-Elemente ihren Status
führen.

## What Changes

- **ISAM-Elemente erhalten Frontend-Signaturen**: Sämtliche in der
  Original-Hilfe dokumentierten ISAM-Anweisungen und -Funktionen werden
  in Grammatik und Signaturprüfung aufgenommen, damit ihre Verwendung
  namentlich diagnostiziert statt als unbekannter Bezeichner behandelt
  wird. Den maßgeblichen Umfang bestimmt das Sprachinventar aus
  `phase-3-runtime-bildschirm`; nach heutigem Stand umfasst er
  mindestens `CREATEINDEX`, `DELETEINDEX`, `SETINDEX`, `GETINDEX$`,
  `INSERT`, `RETRIEVE`, `UPDATE`, `DELETE`, `DELETETABLE`, `MOVEFIRST`,
  `MOVELAST`, `MOVENEXT`, `MOVEPREVIOUS`, `SEEKEQ`, `SEEKGT`, `SEEKGE`,
  `BEGINTRANS`, `COMMITTRANS`, `ROLLBACK`/`ROLLBACK ALL`, `SAVEPOINT`
  (Funktion), `SETMEM` (Funktion), `BOF` sowie das ISAM-Verhalten von
  `EOF`, `DELETE`, `LOF` und `LOC`.
- **ISAM-Datenbanken und Tabellen**: `OPEN … FOR ISAM typname
  tabellenname AS #n` bindet eine Tabelle einer Datenbankdatei an eine
  Dateinummer; das Satzlayout ergibt sich aus dem benannten
  benutzerdefinierten Typ. Tabellen entstehen beim ersten Öffnen,
  `DELETETABLE` entfernt sie.
- **Indizes**: benannte Indizes über eine oder mehrere Spalten, eindeutig
  oder mehrdeutig, mit auf- und absteigender Ordnung; `SETINDEX` wählt
  den aktiven Index und bestimmt damit die Satzreihenfolge, `GETINDEX$`
  liefert ihn zurück.
- **Satzoperationen und Cursor**: `INSERT`, `RETRIEVE`, `UPDATE`,
  `DELETE` arbeiten auf dem aktuellen Satz; die `MOVE`-Familie bewegt den
  Cursor in der Ordnung des aktiven Index, die `SEEK`-Familie positioniert
  über Schlüsselvergleiche (gleich, größer, größer-gleich). `EOF` und
  `BOF` melden das Überlaufen des Cursors am Ende bzw. am Anfang.
- **Transaktionen**: `BEGINTRANS`, `COMMITTRANS`, `ROLLBACK` und
  `ROLLBACK ALL` mit Rücknahme aller Änderungen seit Transaktionsbeginn
  bzw. seit einem Sicherungspunkt; `SAVEPOINT` ist eine **Funktion** und
  liefert die Kennung des gesetzten Sicherungspunkts.
- **Vergleichsreihenfolge**: Die Sortierordnung der Indizes wird unter
  Unicode festgelegt und dokumentiert.
- **ISAM-Fehlersemantik**: Die vorhandenen Fehlercodes 81–89 werden von
  den entsprechenden Situationen ausgelöst (ungültiger Name, Tabelle
  nicht gefunden, Index nicht gefunden, ungültige Spalte, kein aktueller
  Satz, Verstoß gegen einen eindeutigen Index, ungültige Operation auf
  NULL-Index, inkonsistente Datenbank, zu wenig Puffer).
- **Eigenes Datenbankdateiformat**: Die Datenbankdatei ist bewusst nicht
  binärkompatibel zum Vorbild — dieselbe Linie wie bei den UTF-32-
  Records. Das Format wird in `docs/dateiformate.md` beschrieben.

**Non-Goals:** Ein Konvertierungswerkzeug für Datenbankdateien des
Vorbilds; die eingebettete SQL-Erweiterung samt `WHILE SELECT`
(Stufe 2, Ideenspeicher); Mehrprozess-Zugriff über
Betriebssystemgrenzen hinweg jenseits der Satzsperren aus `datei-eio`.

## Capabilities

### New Capabilities

- `isam-datenbank`: indizierter Satzzugriff — Datenbank- und
  Tabellenbindung an Dateinummern, Indexverwaltung, Cursorbewegung und
  Schlüsselsuche, Satzoperationen, Transaktionen, Vergleichsreihenfolge
  und die ISAM-Fehlersemantik (Codes 81–89).

### Modified Capabilities

- `sprach-frontend`: Die Grammatik und die Signaturprüfung SHALL die
  ISAM-Anweisungen und -Funktionen umfassen, sodass ihre Verwendung
  namentlich diagnostiziert wird statt als unbekannter Bezeichner.

## Impact

- `crates/tb-frontend`: neue Anweisungsgrammatik und Signaturen für die
  ISAM-Elemente; die bisherige `Unsupported`-Absenkung von `OPEN … FOR
  ISAM` entfällt.
- `crates/tb-runtime`: neues ISAM-Modul (Speicher, Indizes, Cursor,
  Transaktionen) auf der Dateitabelle und den Recordpuffern aus
  `phase-3-runtime-bildschirm`.
- `crates/tb-vm`: neue Builtin-Indizes für die ISAM-Anweisungen.
- `tests/compat`: neue Korpusprogramme für Indexordnung, Schlüsselsuche,
  Eindeutigkeitsverletzung, Cursorenden und Transaktionsrücknahme.
- `docs/`: `docs/dateiformate.md` um das Datenbankdateiformat erweitert;
  `docs/bibliothek.md` um die ISAM-Elemente; `docs/inventar.md` wechselt
  deren Status auf `implementiert`; `docs/sprachreferenz.md` hält die
  Sortierordnung und die Inkompatibilität des Dateiformats fest.
- PLAN.md: Phase 3 gilt mit diesem Change als abgeschlossen.