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.

## 2026-05-07 — Iteration 4 fertig: LLM-Tooling-Konsolidierung

Drei Sub-Commits, jeder von einem `ailang-implementer`-Aufruf erzeugt
und stichprobenartig vom Orchestrator verifiziert:

- `93fe723` Iter 4a: `ail check --json` mit `Diagnostic`-Struct
  (`severity`, `code`, `message`, `def`, `ctx`). Stabile Codes:
  `unbound-var`, `type-mismatch`, `arity-mismatch`,
  `non-exhaustive-match`, `unknown-ctor`, `unknown-ctor-in-pattern`,
  `nested-ctor-pattern-not-allowed`, `duplicate-def`,
  `unknown-effect-op`, `unknown-type`, `schema-mismatch`. API:
  `check_module(&Module) -> Vec<Diagnostic>`.
- `c652b12` Iter 4b: `ail diff <a> <b> [--json]` als struktureller Top-
  Level-Def-Diff via BLAKE3-Hash. Vier Kategorien (added/removed/
  changed/unchanged), alphabetisch sortiert, Exit-Code 1 bei Diff.
- `74a2005` Iter 4c: IR-Snapshot-Tests in
  `crates/ail/tests/snapshots/{sum,max3,hello,list}.ll`.
  Normalisierung von `target triple`. Update via `UPDATE_SNAPSHOTS=1
  cargo test ir_snapshot_`. Mismatch erzeugt `.actual`-Datei.

Test-Stand: 28 (vorher 19). 7 E2E + 4 IR-Snapshot + 9 ailang-check + 1
ailang-codegen + 7 ailang-core.

**Erledigt aus dem Schulden-Register:**

- Block-Tracking im Codegen ist seit Iter 2 kein Heuristik-Risiko mehr;
  die explizite `current_block: String`-Spur wurde durch Iter 4c jetzt
  zusätzlich von Snapshot-Tests gegen Regression geschützt. Schuld
  geschlossen.

**Neue / präzisierte Schulden:**

1. `check_module` ist **single-shot** — der erste Fehler bricht ab, kein
   Multi-Diagnose-Sammeln. Spec war so, aber das Format suggeriert
   Vec-Semantik. Echter Multi-Diagnose-Refactor wird billiger, sobald
   TIR existiert (zentraler Fehler-Akku durch separate Stufe). Nicht
   jetzt fällig.
2. `source_filename` im IR ist hartkodiert auf `"<module>.ail"`. Solange
   es nur ein Top-Level-Modul gibt, plattform-stabil. Mit Iter 5
   (Modulsystem + Imports) wird der Pfad relevant — dort gleich beim
   Bau pfad-unabhängig halten, sonst kippen die Snapshots.

**Plan Iteration 5:** Modulsystem mit Imports. Cross-Module-Hashing,
Import-Auflösung, mehrere `.ail.json`-Files in einem Build. Multi-
Diagnose-Refactor erst danach.