Phase 4: Formulardateien und Konvertierung

openspec/changes/phase-4-frm/proposal.md

@@ -0,0 +1,63 @@
+# Phase 4 — Formulardateien (`.FRM`) und Konvertierung
+
+## Why
+
+Formulare müssen sich speichern und laden lassen, sonst gibt es weder
+den Formular-Designer der Phase 5 noch den Kompatibilitätstest an den
+Programmen des Vorbilds. Das Vorbild kannte zwei Formate: binär
+(Standard) und Text. Terminal Basic implementiert nur das Textformat —
+das Binärformat ist Nicht-Ziel, seine Dateien müssen aber lesbar werden,
+denn die Beispielprojekte des Originalpakets und die Programme aus
+`github.com/cout/vbdos` liegen **alle** binär vor.
+
+Ein wörtliches Original-Beispiel einer Text-`.FRM` war nicht auffindbar
+(Befund in `docs/dateiformate.md`). Die Serialisierung ist deshalb
+festzulegen und zu dokumentieren, statt sie zu rekonstruieren — der
+einzige Punkt der Phase, an dem die Leitplanke „Referenzverhalten schlägt
+Eleganz" mangels Referenz nicht greift.
+
+Dieser Change hängt weder an den Steuerelementen noch an der
+Ereignisschleife: er beschreibt Formulare, er stellt sie nicht dar.
+
+## What Changes
+
+- **Textformat festlegen und dokumentieren**: `VERSION`-Zeile,
+  verschachtelte `Begin <Klasse> <Name> … End`-Blöcke,
+  `Eigenschaft = Wert`-Zeilen, danach der BASIC-Code des
+  Formularmoduls. Festgelegt werden Kopfzeile, Einrückung, Reihenfolge
+  und die Regel, welche Eigenschaften überhaupt geschrieben werden.
+  Angenommen werden die Versionen 1.00 und 2.00.
+- **Lesen und Schreiben**: Eine `.FRM` wird in eine
+  Formularbeschreibung gelesen und aus ihr wieder geschrieben; das
+  erneute Schreiben einer gelesenen Datei MUST dieselbe Datei ergeben.
+- **Fehlerhafte Dateien**: Unbekannte Klasse, unbekannte Eigenschaft,
+  unpassender Wert und unausgeglichene Blöcke werden mit Datei, Zeile
+  und Name gemeldet, nicht stillschweigend übergangen.
+- **`tbc convert-frm`**: Konvertierung binärer `.FRM` (Magic
+  `FC 08 01 00`) in unser Textformat, als Gegenstück zum
+  Konvertierungswerkzeug des Vorbilds. Das Binärformat wird per Reverse
+  Engineering aus den Beispieldateien des Originalpakets und des
+  cout/vbdos-Repos erschlossen und dokumentiert.
+
+**Non-Goals:** Schreiben des Binärformats; Darstellung oder Ausführung
+der beschriebenen Formulare (Changes `phase-4-objektmodell` und
+`phase-4-steuerelemente`); der Formular-Designer (Phase 5).
+
+## Capabilities
+
+### New Capabilities
+
+- `forms-dateiformat`: Textformat der Formulardateien — Aufbau, Lesen,
+  Schreiben, Fehlermeldungen bei fehlerhaften Dateien — sowie die
+  Konvertierung binärer Formulardateien des Vorbilds.
+
+## Impact
+
+- `crates/tb-ui`: Leser und Schreiber des Textformats auf der
+  Formularbeschreibung aus `phase-4-objektmodell`.
+- `crates/tb-cli`: Unterbefehl `convert-frm`.
+- `docs/dateiformate.md`: Das TODO zur Serialisierung wird durch die
+  festgelegte Fassung ersetzt; das Binärformat wird beschrieben, soweit
+  erschlossen.
+- `tests/`: Beispieldateien und ihre erwartete Formularbeschreibung.
+- PLAN.md: Punkte „`.FRM`-Textformat" und „Konvertierungstool".