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 `if`s 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.

## 2026-05-07 — Workflow-Wechsel: Orchestrator + Agent-Repo

Auf Anregung des Auftraggebers Wechsel auf **Orchestrator-Modus**: ich
delegiere abgrenzte Implementierungs-Brocken an Sub-Agenten und behalte
nur Architektur-Entscheidungen, Reviews und Commit-Disziplin. Vier
spezialisierte Agenten formuliert: implementer, architect, tester,
debugger.

**Wichtige Korrektur:** Auftraggeber hat verlangt, dass die Agenten nicht
in `.claude/agents/` versteckt liegen, sondern als sichtbarer Bestandteil
des Projekts unter `agents/` versioniert werden. DESIGN.md hat einen neuen
Abschnitt "Projekt-Ökosystem" bekommen, der das festhält: AILang ist nicht
nur eine Sprache, sondern Sprachkern + CLI + Examples + Agents + Doku +
Tests, alle gleichwertig.

Aufruf-Schema: System-Prompt-Body aus `agents/<name>.md` als Präfix vor
die konkrete Aufgabe + an `general-purpose`-Agent. Funktional identisch
zum Subagent-Loading aus `.claude/agents/`, aber sichtbar im Repo.

**Plan Iteration 4 (überarbeitet):**

Modulsystem ist aufwändiger als erwartet (Cross-Module-Hashing,
Import-Resolution). Erst die kleineren Tooling-Wins ziehen, dann das
Modulsystem als Iteration 5:

1. **Strukturierte Fehlerausgabe** (`ail check --json` mit Diagnostic-
   Struct, stabile Codes wie `unbound-var`, `type-mismatch`).
2. **`ail diff <a> <b>`** — semantischer Modul-Diff via Hash-Vergleich
   pro Def.
3. **IR-Snapshot-Tests** — Regressions-Schutz für die Codegen-Pipeline.