Old Docs added

docs/Concurrency Model.md

@@ -0,0 +1,46 @@
+### **Projektplan: "Magical & Safe" Concurrency-Modell**
+**Datum:** 21. September 2025, 12:07
+
+#### **Motivation**
+Unser Interpreter besitzt ein solides Fundament für die single-threaded Ausführung. Moderne, datenintensive Anwendungen erfordern jedoch eine robuste und einfach zu handhabende Nebenläufigkeit. Traditionelle Locking-Mechanismen (`TCriticalSection`, Mutexe) sind komplex, extrem fehleranfällig (Race Conditions, Deadlocks) und skalieren schlecht. Ziel ist es, ein modernes Concurrency-Modell direkt in den Sprachkern zu integrieren, das diese Probleme per Design vermeidet.
+
+#### **Ziel**
+Wir erweitern die Sprache um ein Nebenläufigkeits-Modell, das drei Kernziele verfolgt:
+
+1.  **Sicherheit (Safe):** Es muss für den Programmierer unmöglich sein, durch konkurrierende Schreibzugriffe auf geteilten Zustand eine Race Condition zu erzeugen. Die Sprache garantiert die Atomarität von Zustandsänderungen.
+
+2.  **"Magie" (Magical):** Die Sicherheitsmechanismen sollen für den Programmierer **transparent** sein. Er schreibt weiterhin einfachen, sequenziellen Code mit `def` und `assign`. Der Compiler/Binder kümmert sich automatisch um die notwendigen Schutzmaßnahmen, ohne dass der Programmierer explizite Synchronisierungs-Primitive wie `swap!` oder `atom` verwenden muss.
+
+3.  **Performance:** Der durch die Sicherheitsmechanismen entstehende Overhead darf nur dort anfallen, wo er zwingend notwendig ist – also nur bei Zuständen, die tatsächlich geteilt *und* verändert werden.
+
+#### **Geplante Umsetzung & Architektur**
+Um diese Ziele zu erreichen, führen wir eine klare semantische Trennung zwischen unveränderlichen Werten und veränderlichen Identitäten ein und implementieren die "Magie" im Binder.
+
+**1. Das Fundament: Unveränderliche Datenstrukturen (Values)**
+Der Grundpfeiler für sichere Nebenläufigkeit ist, dass Werte (Values) per Definition unveränderlich (immutable) sind. Wenn Daten einmal erzeugt wurden, können sie sich niemals ändern.
+
+* **Todo:** Implementierung einer Kernbibliothek von **persistenten, unveränderlichen Datenstrukturen** (insbesondere Vektoren und Maps), die "Structural Sharing" für effiziente "Updates" nutzen. Bestehende `Series` müssen entweder durch diese ersetzt oder angepasst werden.
+
+**2. Veränderliche Identitäten (Refs)**
+Der veränderliche Zustand wird über **Identitäten** (Referenzen) verwaltet. Eine Identität ist ein stabiler "Container", dessen enthaltener Wert atomar ausgetauscht werden kann. Dies entspricht exakt dem `atom`-Konzept von Clojure.
+
+* **Todo:** Implementierung einer generischen `TAtom<T>`-Klasse in Delphi. Die `Swap`-Methode dieser Klasse wird **lock-frei** mittels einer **`TInterlocked.CompareExchange`-Retry-Schleife** implementiert, um maximale Performance und Skalierbarkeit zu gewährleisten.
+
+**3. Die "Magie": Automatische Promotion im Binder**
+Hier wird der "magische" Aspekt umgesetzt. Der `TAstBinder` wird um eine intelligente Zustandsanalyse erweitert.
+
+* **Logik:**
+    1.  Standardmäßig wird jede Variable als einfacher, performanter Wert im Scope-Speicher behandelt.
+    2.  Der Binder analysiert die Verwendung von Variablen in untergeordneten Scopes (Closures).
+    3.  Sobald der Binder einen **Schreibzugriff (`assign`)** auf eine **Upvalue** (eine Variable aus einem äußeren Scope) entdeckt, wird diese Variable im äußeren Scope automatisch "promotet": Ihr Speicherplatz wird von einem einfachen Wert zu einer Instanz der sicheren `TAtom<T>`-Klasse umgewandelt.
+    4.  Alle nachfolgenden Lese- und Schreibzugriffe auf diese Variable (sowohl im äußeren als auch in allen inneren Scopes) werden vom Binder automatisch in sichere Aufrufe auf dem `TAtom` umgeschrieben.
+
+* **Todo:** Erweiterung des `TAstBinder` um die Logik zur Erkennung von Upvalue-Schreibzugriffen, zur automatischen Promotion von Variablen und zur Umschreibung der entsprechenden AST-Zugriffsknoten.
+
+---
+### **Nächste Schritte (Todo-Liste)**
+
+* [ ] Kernbibliothek für persistente, unveränderliche Datenstrukturen (Vector, Map) entwerfen und implementieren.
+* [ ] Lock-freie `TAtom<T>`-Klasse als primäres Concurrency-Primitiv implementieren.
+* [ ] `TAstBinder` um die "automatische Promotions"-Logik für Upvalues erweitern.
+* [ ] Multi-threaded Unit-Tests schreiben, um die Korrektheit und Sicherheit des neuen Modells unter Last zu verifizieren.