AILang/docs/JOURNAL.md

JOURNAL

Chronologische Notizen für mich. Nicht jede Änderung; nur Entscheidungen, Hindernisse, Beobachtungen, die zukünftige Iterationen brauchen.

2026-05-07 — Tag 0

• Repo initialisiert. Auftrag in CLAUDE.md: LLM-native Sprache, LLVM-Backend.
• Designentscheidungen festgehalten in docs/DESIGN.md.
• Toolchain: rustc 1.94, llvm-config 22.1.3, clang vorhanden.
• Entschieden gegen inkwell zugunsten LLVM-IR-Text-Emit. Begründung im DESIGN.md.
• Workspace-Layout:
  • crates/ailang-core — AST, Type, Hash, JSON-Schema
  • crates/ailang-check — Typchecker (kommt später)
  • crates/ailang-codegen — Lowering + LLVM IR Emit
  • crates/ail — CLI
• MVP-Ziel: examples/sum.ail.json → Binary, das 55 druckt. Erreicht.

2026-05-07 — Architektur-Review nach MVP

Wieder am Pfad? Im Großen ja. Konkrete Beobachtungen:

Was hält:

• JSON-AST + canonical form + content-hash sind alle Lego-Steine, auf denen spätere Tools ohne Refactor aufsetzen können (ail deps, ail diff).
• LLVM-IR-Text-Pipeline arbeitet wie geplant. Keine libllvm-Versionsschmerzen.
• Effekt-Set ist im Typsystem von Anfang an verbaut. Erweiterbar zu row-poly, ohne den Kern zu ändern.

Schulden, die Zinsen tragen:

1. current_block_label_for_phi ist eine Heuristik (siehe codegen). Bei verschachtelten if-Termen wird sie das falsche Block-Label zurückgeben, weil sie rückwärts den Body scannt. Tickend, weil keine Test-Fälle das bisher triggern. Muss als nächstes fixiert werden, bevor neue Sprachfeatures dazu kommen.
2. Kein typed-AST. Codegen liest direkt das Quell-AST und verlässt sich darauf, dass der Typchecker vorher lief. Für MVP OK; sobald ADTs oder Closures dazukommen, brauche ich eine getrennte typisierte IR-Stufe (TIR).
3. hash-Feld ist nicht im AST. Aktuell hashen wir das Def-Objekt direkt. Wenn ich Hashes später als Felder mitserialisiere (Caching), muss der Hash das Feld vor der Berechnung ausschließen.

Plan Iteration 2 (jetzt):

1. Block-Label-Tracking sauber machen, verschachteltes-if-Test.
2. Strings als Literal + io/print_str.
3. Hello-world-Beispiel als zweiten E2E-Test.
4. CLI: --json-Output für maschinelle Konsumenten überall, wo es passt.

Plan Iteration 3:

ADTs + Pattern Matching. Das ist der nächste große Sprung. Erfordert typisierte IR-Stufe (TIR), weil Pattern Matching zu Decision-Trees lowered wird, was eine andere Form ist als der AST.

2026-05-07 — Iteration 2 fertig

• Block-Label-Tracking robust (verschachtelte ifs funktionieren). Test max3_picks_largest schützt das.
• Strings als Lit::Str { value }, Type Str -> LLVM ptr, mit io/print_str Effekt-Op. examples/hello.ail.json druckt einen String.
• CLI: manifest --json, builtins --json für Tool-Konsumenten.
• ail deps [--of NAME] [--json] listet Aufruf-Edges. Effekt-Ops sind als effect:NAME markiert, damit ein Konsument sie filtern kann.

Architektur-Check: Keine strukturellen Abweichungen. Codegen liest noch direkt das Quell-AST (TIR-Stufe wird mit ADTs in Iteration 3 nötig).

2026-05-07 — Iteration 3 fertig: ADTs

• TypeDef im AST mit Ctors. Ein Ctor hat name und fields: [Type...].
• Term::Ctor (Konstruktion) und Term::Match (Pattern Matching).
• Patterns: Wild, Var, Lit, Ctor { ctor, fields }. Im MVP sind nested Ctor-Patterns NICHT erlaubt — Sub-Patterns müssen Var oder Wild sein.
• Typchecker mit Type-Registry und ctor_index (ctor-name → ADT). Im Match wird Exhaustiveness gegen die volle Konstruktormenge geprüft. Negativ-Test schützt das.
• Codegen: Boxed-Heap-Layout. Pro Ctor-Anwendung malloc(8 + 8*n) Bytes; Tag in offset 0, Felder ab offset 8 (8-Byte-Slots, native typed load/store). Match: load tag + switch + arm-blocks + phi am Join.
• examples/list.ail.json (Cons/Nil-Liste, sum_list über match) liefert 42.

Erstaunlich problemlos. Die Architekturentscheidungen aus Tag 0 haben sich ausgezahlt: opaque ptr in LLVM 22 macht Boxed-Layout fast ohne Glue-Code möglich; das Effekt-Tracking blieb von ADTs unberührt; der JSON-AST nimmt neue Knoten-Typen sauber auf.

Gewachsene Schulden:

1. Codegen liest immer noch direkt den Quell-AST. Die Versuchung war stark, ohne TIR weiterzumachen — und hat funktioniert, weil meine Match-Restriktionen flach sind (keine nested Patterns). Sobald nested Patterns kommen, braucht es ein Decision-Tree-Lowering, das ohne TIR nicht sauber wird. Schulden anerkannt; nicht jetzt fällig.
2. Kein GC. Heap leakt. Akzeptabel für Demo-Programme; muss vor jedem längerläufigen Programm angegangen werden. Optionen für Phase 4: Refcount, Boehm-GC-Linkage, Region-Inference.
3. Pretty-Printer für ADT-Werte zur Laufzeit fehlt. io/print_int reicht für Demos, aber ein generisches show :: a -> Str für ADTs wäre wertvoll. Erfordert dispatch über tag — machbar, aber nicht jetzt.

Plan Iteration 4:

Die nächsten Schritte sind weniger eindeutig. Drei Kandidaten in Prioritätsreihenfolge:

1. Modulsystem (Imports). Aktuell ist alles in einem Modul. Mit mehreren Modulen + Cross-Module-Hashing wird die Sprache erst praktikabel für mehrere Defs.
2. Strukturierte Fehlerausgabe (ail check --json). Damit Tools auf Typfehler reagieren können, ohne Text zu parsen.
3. Closures / höherwertige Funktionen. Erfordert Closure-Konvertierung und ist ein größerer Schritt.

Iteration 4 wird (1) + (2) — beides macht das LLM-Tooling stärker und hat moderates Risiko.