Plan Phase 6 runtime, P-code libraries and Gitea releases

openspec/changes/phase-6-03-pcode-bibliotheken-und-linker/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-07

openspec/changes/phase-6-03-pcode-bibliotheken-und-linker/design.md

@@ -0,0 +1,32 @@
+## Context
+
+`project.rs::link` verbindet schon Modulprodukte und korrigiert Prozedur-, Global-, UDT-, String-, DATA- und Sprungtabellenreferenzen. Dafür benötigt es derzeit AST-Deklarationen und COMMON-Metadaten; der Compiler importiert Deklarationen vor der Absenkung. `CompiledModule`/TBC enthält viele Laufzeitdaten, ist aber ein vollständiges Programm statt eines austauschbaren unverknüpften Modulprodukts. `Manifest` akzeptiert bislang BAS/FRM, der IDE-Quelllader behandelt Mitglieder als Dokumente. 02 liefert den nativen `tbrt`-Runner und sichere EXE-Verpackung.
+
+## Goals / Non-Goals
+
+**Goals:** Vorhandene Übersetzung und Tabellenauflösung für quellfreie Bibliotheksmodule öffnen, denselben Linkdienst in CLI und IDE verwenden und die Runtime einmal im Executable halten.
+
+**Non-Goals:** C-ABI, native `.lib`/`.a`-Projektbibliotheken, DLL/QLB-Kompatibilität, eigener Maschinenobjekt-Linker, JIT/AOT von BASIC, Paketregistry, dynamisches Nachladen von TBL zur Laufzeit oder Linkzeitoptimierung. Die Runtime selbst wird weiterhin von Rust nativ kompiliert.
+
+## Decisions
+
+1. TBL als einfacher versionierter binärer Container mit eigenem Magic, festen Integerbreiten, definierter Byteordnung und längengeprüften Abschnitten. Vorhandene TBC-Kodier-/Laderbausteine wiederverwenden. Speichern: geordnete unverknüpfte Modulprodukte, exportierte Prozedur-/Konstanten-/Typdeklarationen, typisierte offene Imports, COMMON-Angaben, Initialisierungsgrenzen, Forms-Katalog/Anfangswerte/Ereignisse und Quellortmetadaten. Kein vollständiger Quell-AST und kein Rust-Speicherlayout im Dateivertrag. Reines Umbenennen eines vollständig gelinkten TBC bewahrt nicht die benötigten Linkinformationen.
+2. Die AST-abhängigen Eingaben der bestehenden Linkfunktion auf die tatsächlich nötigen Modul-/Symbolmetadaten reduzieren. Quellmodule erzeugen dieselben Metadaten wie der TBL-Lader. Deklarationen aus TBL vor der Semantikanalyse des Verbrauchers importieren; Laufzeitcode nicht rekonstruieren oder erneut kompilieren. Sämtliche Tabellenreferenzen einschließlich Forms, Ereignissen, Typen und physischen Source-IDs beim Zusammenführen abbilden. Abschließend das vollständige Kompilat validieren. Bestehende Größenlimits kontrolliert prüfen, nicht durch Integer-Casts abschneiden.
+3. Bibliotheksbau darf typisierte DECLARE-Imports offen halten; für externe Konstanten/Typen werden die Deklarationen über angegebene TBL-Eingaben bereitgestellt. Alle zum Bau als Projektmitglieder angegebenen Module werden in die Ausgabe übernommen; keine versteckten Kopien nativer Runtime und kein Dead-Code-Eliminator. Exporte folgen den bisherigen Sichtbarkeits-/Namensregeln. Beim finalen Linken müssen alle Imports eindeutig und typkompatibel aufgelöst sein. Gegenseitige Prozeduraufrufe sind zulässig; es gibt keine separate rekursive Paketauflösung.
+4. `.MAK` nimmt `.tbl` zusätzlich als Dateieintrag auf. Relative Pfade, Fallunabhängigkeit, Reihenfolge und kanonische Duplikatprüfung wiederverwenden. Ein TBL-Eintrag expandiert seine Module an dieser Position; zusätzliche CLI-Bibliotheken folgen in Argumentreihenfolge. Doppelte Modulidentitäten sind Fehler, keine stillen Überschreibungen. Abhängigkeiten werden nur aus der expliziten Eingabemenge aufgelöst; keine Netzsuche oder implizite Suche nach ursprünglichen Entwicklerpfaden. Reexport durch Library-Bau flacht enthaltene Modulprodukte ab; überlappende Bibliotheken werden beim späteren Einbinden als Duplikat diagnostiziert.
+5. Initialisierung folgt dem vorhandenen Projektvertrag: Anfangswerte vor Modulrümpfen; die Startdatei des Verbraucherprojekts bestimmt den ersten Quellmodulrumpf und gegebenenfalls das Startformular, danach übrige expandierte Module in relativer Reihenfolge. Bibliotheksmodulrümpfe sind normale Modulrümpfe, keine zusätzliche versteckte Init-Sitzung. TBL bewahrt ihre Modulreihenfolge, aber keine aktive Startdatei/Startformularentscheidung des Bibliotheksbauprojekts. Forms können vom Verbraucher aktiviert werden. RUN setzt das gesamte verknüpfte Programm über den bestehenden VM-Pfad zurück.
+6. Konkrete CLI-Oberfläche: `tbc build lib.mak --library --output lib.tbl`; `tbc link app.mak lib.tbl --output app.tbc`; mit `--exe --target <triple>` wird stattdessen ein Executable erzeugt. `tbc link app.tbc --exe ...` darf ein bereits vollständiges TBC verpacken, nimmt dafür aber keine zusätzlichen TBL an: nachträgliches Linken ohne Modulmetadaten wird diagnostiziert. `tbc build app.mak [--exe]`, `run` und `check` verarbeiten die MAK-Bibliotheken über denselben Dienst. `--library` und `--exe` schließen sich aus; TBL-/TBC-Ausgabe benötigt kein natives Target und weist `--target` in diesen Modi als unpassend ab. Kein neues `tblink`-Programm.
+7. Shared Linkdienst bleibt unterhalb von CLI/IDE im vorhandenen VM-/Projektbereich. Der Exportbereich aus 02 verpackt nur das vollständig verknüpfte TBC mit `tbrt`; er enthält keinen zweiten Compiler. 04 bindet Bibliotheksmitglieder, Start/Check/Debugger und Make-Aktionen an. Compiler-Caches und IDE-Auftragsstempel müssen die tatsächlichen Bibliotheksbytes einbeziehen; Änderungen an einer TBL dürfen kein altes Linkresultat wiederverwenden.
+8. TBL und TBC sind auf allen vier Zielen verwendbar, solange Format und Runtime kompatibel sind. Nur `tbrt` und das fertige Executable haben ein natives Target. Library-Bau und P-Code-Linken sind ausschließlich TB-Operationen; keine C-/Rust-Toolchain beim Anwender. `--exe` verwendet die Vorlagen-/Signierprüfung aus 02. Ausgaben werden über dessen Staging-/No-clobber-Vertrag publiziert; alle eingelesenen TBL-Dateien gehören zu den geschützten Eingaben.
+
+## Risks / Trade-offs
+
+- TBC enthält noch nicht alle unverknüpften Informationen → separates TBL-Metadatenschema und Vergleich eines Quellprojekts mit seinem TBL-Ersatz, keine AST-Serialisierung als Abkürzung.
+- Remapping beschädigt seltene Referenzen → Gegenproben mit UDT/COMMON, DATA/RESTORE, Forms-Ereignissen und Fehlerorten aus mehreren Libraries.
+- Modulrümpfe haben Seiteneffekte → Reihenfolge transparent dokumentieren und gegen das entsprechende Quellprojekt testen; kein stilles Umordnen nach Symbolabhängigkeiten.
+- Geänderte TBL bleibt im Cache → Inhaltsidentität in Compiler-/IDE-Snapshot, inklusive Prüfung vor Veröffentlichung.
+- Bestehende BASIC-Kollisionen erscheinen in Bibliotheken → gleiche Diagnosen statt neuer Namensraumsyntax. Gleichnamige Module werden eindeutig abgewiesen.
+
+## Migration Plan
+
+Additive Dateiendung, MAK-Mitgliedsart und CLI-Befehle; reine Quellprojekte und vorhandenes vollständiges TBC behalten ihr Verhalten. Versionen bei inkompatiblen Änderungen explizit prüfen und Neubau der betroffenen Bibliothek verlangen. Keine Migration historischer DOS-LIB/QLB. IDE-Anbindung in 04, identische TBL auf allen Zielrunnern in 06, Benutzerweg in 07. Der verworfene native Bibliotheksentwurf war nicht implementiert und erfordert keine Produktdatenmigration.

openspec/changes/phase-6-03-pcode-bibliotheken-und-linker/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+BASIC wird als P-Code ausgeführt; wiederverwendbare BASIC-Bibliotheken benötigen deshalb ein linkbares TB-Format. Die native Runtime steckt bereits in `tbrt` aus 02. Ein zusätzlicher C-ABI-/Systembibliotheksexport würde unnötige Erzeugungswerkzeuge und eine zweite Aufrufschnittstelle verlangen.
+
+## What Changes
+
+- `.tbl` als versioniertes, plattformunabhängiges Format für übersetzte BASIC-Module mit Symbolen, Signaturen, Imports und benötigten Daten einführen. Die native Runtime bleibt ausschließlich Bestandteil von `tbrt`.
+- `tbc build --library` erzeugt `.tbl`; `tbc link` verbindet ein Hauptprojekt und `.tbl`-Bibliotheken zu einem vollständigen `.tbc` beziehungsweise über `--exe` mit der passenden `tbrt`-Vorlage zu einem eigenständigen Executable.
+- Den vorhandenen Projektlinker erweitern: Bibliotheken sind ohne ihre BAS-/FRM-/Include-Quellen nutzbar, Auflösung und BASIC-Semantik bleiben gemeinsam.
+- `.tbl`-Verweise als geordnete `.MAK`-Einträge sowie explizite CLI-Eingaben unterstützen. Fehlende oder inkompatible Symbole, Typen, Formate und Abhängigkeiten vor Ausgabe diagnostizieren.
+- Erzeugung und Linken benötigen weder C-/Rust-Compiler noch nativen Linker beim Anwender. Die IDE bindet denselben Dienst in 04 an.
+
+## Capabilities
+
+### New Capabilities
+
+- `pcode-bibliotheken`: Portables TBL-Format, quellfreie Wiederverwendung, gemeinsamer P-Code-Linkvertrag und CLI-/Projektintegration.
+
+### Modified Capabilities
+
+Keine. TBL ist eine additive Projekt-/Buildfähigkeit; die Anpassung der bisherigen IDE-Exportbeschreibungen erfolgt mit 04. Bestehende reine Quellprojekte und vollständige TBC-Programme behalten ihren Vertrag.
+
+## Impact
+
+`tb-vm/src/project.rs`, `bytecode.rs`, `project_io.rs`, Frontend-Deklarationsimport und `tb-cli/src/main.rs`; Wiederverwendung der sicheren Veröffentlichung und `tbrt`-Verpackung aus [02](../phase-6-02-native-executables/proposal.md). Abhängigkeit: 02. IDE-Dokumentmodell, Ausführung, Debugger und Make-Anbindung folgen in 04; plattformübergreifende Verbraucherprüfungen in 05/06, Dokumentation und Gesamtabnahme in 07. Dieser Entwurf ersetzt den noch nicht implementierten Entwurf `phase-6-03-native-bibliotheken` vollständig.

openspec/changes/phase-6-03-pcode-bibliotheken-und-linker/specs/pcode-bibliotheken/spec.md

@@ -0,0 +1,51 @@
+## Purpose
+
+Ermöglicht die quellfreie Wiederverwendung übersetzter BASIC-Module als portable TBL-Bibliotheken und deren Verknüpfung zu vollständigen Programmen für dieselbe TBVM.
+
+## ADDED Requirements
+
+### Requirement: Portables TBL-Bibliotheksformat
+`tbc build --library` und Make Library SHALL eine `.tbl` mit übersetzten BASIC-Modulen, exportierten Deklarationen, typisierten Imports sowie den benötigten Daten und Forms-Ressourcen erzeugen. Sie SHALL ohne ihre ursprünglichen BAS-/FRM-/Include-Quellen weiterverwendbar sein. Das Format SHALL versioniert und unabhängig von Windows/Linux/macOS sowie amd64/arm64 sein. Native Runtime und plattformspezifischer Maschinencode MUST NOT Bestandteil der TBL sein; die native Runtime SHALL im Ziel-`tbrt` liegen.
+
+#### Scenario: Bibliothek auf einem anderen Ziel verwenden
+- **WHEN** dieselben TBL-Bytes mit kompatiblen Terminal-Basic-Versionen für die vier Releaseziele verknüpft werden
+- **THEN** liefern die Programme bei gleichen Eingaben dieselben BASIC-Ergebnisse ohne Neubau der Bibliothek aus Quellen
+
+### Requirement: Gemeinsamer Linkbefehl
+`tbc link` SHALL ein Hauptprojekt und angegebene TBL-Bibliotheken zu einem vollständig aufgelösten TBC-Programm verbinden. Mit `--exe` SHALL derselbe Befehl dieses Programm in die passende vorgebaute `tbrt`-Vorlage einbetten und ein natives eigenständiges Executable erzeugen. `tbc build`, `run` und `check` SHALL bei Projekten mit TBL-Verweisen dieselbe Auflösung verwenden. Erzeugen und Linken SHALL ohne C-/Rust-Compiler oder nativen Linker beim Anwender möglich sein; dokumentierte Systemvoraussetzungen zur EXE-Finalisierung bleiben anwendbar.
+
+#### Scenario: Quellfreie Bibliotheksnutzung bis zur EXE
+- **WHEN** nach dem TBL-Bau deren Quellen entfernt werden und ein Verbraucherprojekt über `tbc link --exe` verknüpft wird
+- **THEN** läuft das Executable anschließend ohne separate TBL/TBC, separat installiertes tbrt/tb/tbc oder Buildtoolchain mit dem korrekten Bibliotheksverhalten
+
+### Requirement: Explizite Bibliothekszuordnung
+TBL-Dateien SHALL als geordnete MAK-Einträge relativ zur Projektdatei mit der bestehenden DOS-großschreibungsunabhängigen Pfadauflösung verwendbar sein. `tbc link` SHALL zusätzliche TBL-Eingaben ausdrücklich annehmen. Bibliotheksmodule SHALL ihre Identität und Deklarationen behalten; ein TBL-Eintrag MUST NOT als editierbare Quelltextdatei oder als Startdatei interpretiert werden. Externe Bibliotheksabhängigkeiten SHALL aus den angegebenen Eingaben aufgelöst werden; fehlende Abhängigkeiten MUST vor Programmausgabe diagnostiziert werden.
+
+#### Scenario: Projekt mit verschobener Bibliothek
+- **WHEN** ein Projekt und seine relativ referenzierte TBL gemeinsam in ein anderes Verzeichnis verschoben werden
+- **THEN** bleibt das Projekt ohne Bibliotheksquellen verknüpfbar; fehlt stattdessen die TBL, nennt die Diagnose die fehlende Datei und ihren Projektbezug
+
+### Requirement: Eindeutige und typgeprüfte Verknüpfung
+Der Linkpfad SHALL Imports eindeutig mit kompatiblen Exporten verbinden und die bestehenden Regeln für Namen, Konstanten, UDTs, COMMON sowie Prozedursignaturen erhalten. Fehlende Definitionen, mehrdeutige Exporte, inkompatible Parameter-/Ergebnistypen, doppelte Modulidentitäten und überschrittene Formatgrenzen SHALL vor Programmausführung mit konkretem Bezug abgewiesen werden. Bibliotheken SHALL typisierte offene Imports speichern können; ein ausführbares Endprodukt MUST NOT unaufgelöste Imports enthalten.
+
+#### Scenario: Bibliothek benötigt eine weitere Bibliothek
+- **WHEN** Bibliothek A eine typisierte Prozedur aus B importiert und nur A zum Verbraucher angegeben wird
+- **THEN** scheitert das Linken mit dem fehlenden Symbol; nach Hinzufügen eines signaturkompatiblen B funktioniert der Aufruf, während ein inkompatibles B eine Typdiagnose auslöst
+
+#### Scenario: Mehrdeutiges Symbol
+- **WHEN** zwei eingebundene Module einen nach bestehenden Sprachregeln mehrdeutigen Export anbieten
+- **THEN** meldet der Linker den Namenskonflikt mit beiden Herkunftsmodulen und wählt keine zufällige Definition
+
+### Requirement: Erhaltene BASIC- und Laufzeitsemantik
+Verknüpfte Bibliotheksmodule SHALL dieselben Wert-, BYREF-/BYVAL-, Array-, UDT-, COMMON-, DATA-/RESTORE-, Forms- und Fehlerregeln wie entsprechende Quellmodule erfüllen. Globale Anfangswerte SHALL vor Ausführung bereitstehen; Modulrümpfe SHALL in der dokumentierten erweiterten Projektreihenfolge mit demselben Kontrollfluss wie die entsprechenden Quellmodule ausgeführt werden; bloße Symbolverweise SHALL keine zusätzliche Modulinitialisierung auslösen. Die Startauswahl SHALL dem Hauptprojekt gehören. RUN ohne Ziel SHALL auch den Bibliothekszustand neu initialisieren. Physische Fehlerorte und BASIC-Zeilenlabels SHALL trotz fehlender Bibliotheksquellen erhalten bleiben.
+
+#### Scenario: Quellmodule durch TBL ersetzen
+- **WHEN** Bibliotheksmodule eines Projekts durch ihre TBL in derselben Modulreihenfolge ersetzt und direkte sowie verknüpfte Variante mit gleichen Ereignissen gestartet werden
+- **THEN** stimmen Initialisierung, BYREF-Änderungen, strukturierte Werte, Forms-Ereignisse und Fehlerorte überein; nach RUN besitzen beide denselben frischen Anfangszustand
+
+### Requirement: Validierung und geschützte Ausgabe
+TBL-Lader und Linker SHALL Format-/P-Code-/Runtime-Kompatibilität, Grenzen und alle Tabellen-/Symbolverweise prüfen. Beschädigte oder inkompatible Bibliotheken SHALL kontrolliert abgewiesen werden. Fehler, Abbruch oder Ausgabekonflikte SHALL bestehende Ausgaben und sämtliche Eingaben einschließlich Bibliotheken erhalten. Erfolg SHALL erst nach vollständiger validierter Veröffentlichung gemeldet werden.
+
+#### Scenario: Beschädigter Container oder Ausgabe auf Eingabe
+- **WHEN** eine abgeschnittene TBL geladen wird oder das Linkziel eine der Eingabebibliotheken überschreiben würde
+- **THEN** scheitert der Vorgang mit konkreter Diagnose, führt keinen BASIC-Code aus und erhält bestehende Eingaben und Ausgaben

openspec/changes/phase-6-03-pcode-bibliotheken-und-linker/tasks.md

@@ -0,0 +1,24 @@
+## 1. Bibliotheksprodukt und Format
+
+- [ ] 1.1 AST-abhängige Linkinformationen in kompakte gemeinsame Modulmetadaten überführen; bestehende reine Quellprojekt-/Cachetests müssen Verhalten, Diagnosen und Wiederverwendung erhalten.
+- [ ] 1.2 Versionierten TBL-Leser/-Schreiber für unverknüpfte Produkte, Deklarationen, COMMON, Forms und Quellorte implementieren; Roundtrip sowie beschädigte Längen, Referenzen, Versionen und Grenzwerte prüfen.
+- [ ] 1.3 Library-Kompilation mit typisierten offenen Imports und bestehender Exportsichtbarkeit anbinden; eine Bibliothek mit DECLARE-Import muss ohne dessen Implementierung baubar sein, ungültige Deklarationen müssen scheitern.
+
+## 2. Gemeinsames Linken
+
+- [ ] 2.1 TBL-Deklarationen vor der Verbraucher-Semantikanalyse importieren und Quell-/Libraryprodukte gemeinsam verknüpfen; zwei Bibliotheken mit Abhängigkeit müssen ohne Bibliotheksquellen funktionieren, fehlende/mehrdeutige/inkompatible Symbole und doppelte Module müssen konkrete Diagnosen liefern.
+- [ ] 2.2 Vollständiges Remapping und Initialisierung prüfen; Vergleichsprojekte müssen BYREF/BYVAL, Arrays, UDTs, COMMON, Konstanten, DATA/RESTORE, Forms-Ereignisse, Fehlerorte und RUN mit äquivalenten Quellmodulen abgleichen.
+- [ ] 2.3 MAK-Laden/-Schreiben um geordnete TBL-Einträge erweitern; Verschieben/Save-As, Fallunabhängigkeit, Duplikate, fehlende Dateien, TBL als unzulässige Startdatei und unveränderte reine Quellprojekte testen.
+- [ ] 2.4 Bibliotheksinhalt in die Compiler-Cacheidentität aufnehmen; Austausch einer TBL einschließlich gleicher Dateigröße muss Linkresultat und betroffene Deklarationen aktualisieren.
+
+## 3. CLI und Ausgabe
+
+- [ ] 3.1 `tbc build --library` und `tbc link` mit expliziten TBL-Eingaben implementieren sowie run/build/check für MAK-Bibliotheken anbinden; CLI-Tests müssen gültige Beispiele, unveränderten TBC-Standard und unzulässige Flag-/Eingabekombinationen prüfen.
+- [ ] 3.2 `tbc link --exe` mit der tbrt-Verpackung aus 02 verbinden; ein ohne Bibliotheksquellen gelinktes Programm muss anschließend ohne TBL/TBC/tbrt/tb/tbc-Installation starten und dieselben Resultate liefern.
+- [ ] 3.3 TBL-/Linkausgabe über die geschützte Veröffentlichung aus 02 führen; Abbruch, Schreibfehler, No-clobber-Konflikt und Ausgabe auf eine Eingabebibliothek dürfen keine Eingabedaten oder alten Ziele beschädigen.
+
+## 4. Abnahme und Übergabe
+
+- [ ] 4.1 Ein identisches TBL-Artefakt auf Windows amd64, macOS arm64 und Linux amd64/arm64 mit separaten BASIC-Verbrauchern verknüpfen; Prüfsumme und echte Zielausführung müssen Portabilität ohne Neubau der Library beweisen.
+- [ ] 4.2 Format-/Befehls-/Initialisierungsvertrag und Werkzeugfreiheit dokumentieren; Beispiele müssen mit ausgelieferten TB-Tools ohne C-/Rust-Compiler oder nativen Linker laufen und fehlende EXE-Voraussetzungen korrekt benennen.
+- [ ] 4.3 Sämtliche Spec-Szenarien mit Ergebnissen zuordnen und Übergabe an IDE 04/Actions 06 vorbereiten; fokussierte Link-/CLI-Tests, Workspace-Regressionen, Clippy, Format- und OpenSpec-Prüfung müssen ohne offenen Befund bestehen.