TerminalBasic/openspec/changes/archive/2026-09-07-phase-6-03-pcode-bibliotheken-und-linker/design.md

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. 03 wird mit Backend-/CLI-Regressionen, festem TBL-Artefakt samt Prüfsumme und Verbraucherprobe auf dem verfügbaren Host abgenommen. IDE-Anbindung in 04, echte Ausführung derselben TBL-Bytes auf allen vier Zielsystemen in 05, zentraler Cross-Paketbau und paketgebundene Zielnachweise in 06, Benutzerweg in 07. Diese Aufteilung ändert den Portabilitätsvertrag nicht; fehlende Zielausführungen bleiben dort offen. Der verworfene native Bibliotheksentwurf war nicht implementiert und erfordert keine Produktdatenmigration.