# AILang Design — Index

> **Status: RETIRED (paused) as of 2026-06-03.** No further compiler or
> language work is planned for now. The project's differentiating thesis —
> that a language purpose-built for LLM authorship makes LLM authors
> measurably more correct — did not find empirical support in the project's
> own cross-model measurements: the optimal surface is model-relative (a
> redundant-structure crutch helps a small model and *hurts* a frontier one),
> a compiler-in-the-loop is not an equaliser, and for a frontier author AILang
> is at best neutral versus a familiar language given a scan. The
> hallucination-robustness pillar (content-addressed symbols) was separately
> falsified and removed (#66). Evidence corpus:
> `experiments/2026-05-12-cross-model-authoring/format-findings.md`. The
> language design below remains a sound small ML/effect language and the
> measurement harness remains the project's most durable output; the git
> history and the `design/` ledger stand as the record. This is a pause, not
> a deletion — reversible if a new framing makes the remaining work worthwhile.

The sole addressable entry point. Every contract and model is
reached from here. A contract is a prescriptive, test-linked
invariant; a model is a whitepaper narrative. `ratifying-test` names
the green test that proves a contract still holds. `link` is
polymorphic: a `design/` file, or the authoritative source `//!`
header when the code is the single source of truth.

## Project framing

### Goal

AILang is a programming language for LLM authors. It compiles to LLVM IR.
Performance: native, no GC for the MVP.

Optimised for:

- **Machine readability** over human ergonomics. The source is structured.
- **Local reasoning.** Every definition carries its full type and effects.
- **Provability.** Pure core language, explicit effects, optional refinements.
- **Robustness against hallucinations.** Symbols are hashable; tools can verify
  existence without spending context window.


### Project ecosystem

AILang is not just a language but an ecosystem. The language on its own is
only valuable when its surroundings make it usable, checkable, and
extensible for its target user (LLM authors). The repo therefore contains
several equally important components — none of them optional, all of them
evolving in lockstep with the language:

- **Language core** (`crates/ailang-core`, `crates/ailang-check`,
  `crates/ailang-codegen`): AST, type system, codegen.
- **Surface forms** (`crates/ailang-surface`, `crates/ailang-prose`):
  the LLM-facing renderings of a module. `ailang-surface`
  is the lossless Form-A printer/parser — the canonical
  [authoring surface](contracts/0001-authoring-surface.md), with a
  round-trip property `parse ∘ print = id` gating every release. `ailang-prose`
  is the lossy Form-B projection — human-readable prose for review and
  edit, with no parser; re-integration goes through the
  LLM-mediator round-trip documented in `docs/PROSE_ROUNDTRIP.md`.
- **CLI** (`crates/ail`): toolchain for tooling consumers — `manifest`,
  `describe`, `deps`, `check`, `build`, `parse`, `render`, `prose`,
  `merge-prose`, etc., preferably with `--json` for machine consumption.
- **Examples** (`examples/`): canonical `.ail.json` programs. They are
  specification anchors, not demos — the E2E suite hangs off them.
- **Skills** (`~/dev/skills/` plugin, wired in via
  `.claude/dev-cycle-profile.yml`): specialised disciplines
  (`brainstorm`, `planner`, `implement`, `audit`, `debug`,
  `fieldtest`, `docwriter`, `boss`) plus the agent rosters
  they dispatch. They form the project's development
  methodology; the plugin is versioned separately, the
  per-project profile is in-tree.
- **Design ledger** (`design/`): `design/INDEX.md` (this file — the
  sole addressable spine for canonical state), `design/contracts/`
  (test-linked invariants), `design/models/` (onboarding
  whitepapers).
- **Docs** (`docs/`): `specs/` (per-milestone design specs),
  `plans/` (per-iteration implementation plans). Project history
  lives in `git log`; the forward queue lives in the Gitea issue
  backlog (http://192.168.178.103:3000/Brummel/AILang/issues).
- **Tests**: unit tests per crate plus E2E in `crates/ail/tests/e2e.rs`. Every
  new compiler path needs a test, otherwise the feature does not count as done.


### Project language: English

All in-tree content is written in English: source code (identifiers,
comments, string literals, CLI help), design documents, agent
prompts, READMEs, commit messages, examples, and `CLAUDE.md`. The live
conversation between user and me stays German for ergonomic reasons;
everything that lands in git is English. This keeps diffs and tooling output
uniform and matches the audience for AILang (LLM authors), for whom English
is the default.


## Contracts
| id | consumer / lifetime | ratifying-test | link |
|----|---------------------|----------------|------|
| feature-acceptance   | brainstorm-gate / stable      | CLAUDE.md                          | design/contracts/0004-feature-acceptance.md |
| authoring-surface    | LLM author / stable           | crates/ailang-surface/tests/round_trip.rs       | design/contracts/0001-authoring-surface.md |
| roundtrip-invariant  | every release / stable        | crates/ailang-surface/tests/round_trip.rs       | design/contracts/0009-roundtrip-invariant.md |
| language-constraints | LLM author / stable           | crates/ailang-core/src/ast.rs (no thunk/ref/IORef node — by construction) | design/contracts/0015-language-constraints.md |
| memory-model         | LLM author / stable           | crates/ailang-check/src/uniqueness.rs + linearity.rs (in-source mod tests) | design/contracts/0008-memory-model.md |
| data-model           | LLM author / stable           | crates/ailang-core/tests/design_schema_drift.rs | design/contracts/0002-data-model.md |
| mangling             | codegen / stable              | crates/ail/tests/eq_ord_e2e.rs            | crates/ailang-codegen/src/lib.rs //! |
| env-construction     | codegen / stable              | crates/ailang-check/tests/duplicate_ctor_pin.rs | crates/ailang-codegen/src/lib.rs //! |
| qualified-xref       | check→codegen / stable        | crates/ail/tests/codegen_import_map_fallback_pin.rs | crates/ailang-check/src/lower_to_mir.rs (classify_callee) + design/contracts/0018-check-codegen-boundary.md |
| frozen-value-layout  | embedding ABI / one-way-frozen| crates/ailang-codegen/tests/embed_record_layout_pin.rs | design/contracts/0006-frozen-value-layout.md + runtime/rc.c §layout |
| float-semantics      | LLM author / stable           | crates/ail/tests/eq_float_noinstance.rs   | design/contracts/0005-float-semantics.md |
| typeclasses          | LLM author / stable           | crates/ail/tests/show_no_instance_e2e.rs  | design/contracts/0013-typeclasses.md |
| method-dispatch      | LLM author / stable           | crates/ail/tests/show_no_instance_e2e.rs  | design/contracts/0016-method-dispatch.md |
| prelude-classes      | LLM author / stable           | crates/ail/tests/show_no_instance_e2e.rs  | design/contracts/0017-prelude-classes.md |
| str-abi              | runtime ABI / stable          | crates/ail/tests/e2e.rs (Str path)        | design/contracts/0011-str-abi.md + runtime/str.c §heap-Str |
| tail-calls           | codegen / stable              | crates/ailang-check/src/lib.rs (in-source tail_call_in_non_tail_position_is_rejected) | design/contracts/0012-tail-calls.md |
| honesty-rule         | architect+grounding / stable  | crates/ailang-core/tests/docs_honesty_pin.rs | design/contracts/0007-honesty-rule.md |
| embedding-abi        | embedding host / stable       | crates/ailang-codegen/tests/embed_record_layout_pin.rs | design/contracts/0003-embedding-abi.md |
| scope-boundaries     | architect+author / stable     | crates/ailang-core/tests/effect_doc_honesty_pin.rs | design/contracts/0010-scope-boundaries.md |
| verification         | architect / stable            | crates/ail/tests/ir_snapshot.rs (+ round_trip, hash_pin, e2e) | design/contracts/0014-verification.md |
| check-codegen-boundary| architect / stable           | crates/ailang-check/tests/lower_to_mir_ty.rs (callee_classification_builtin_and_static) | design/contracts/0018-check-codegen-boundary.md |

## Models
| id | consumer / lifetime | link |
|----|---------------------|------|
| rc-uniqueness     | onboarding / evolves | design/models/0004-rc-uniqueness.md |
| typeclasses       | onboarding / evolves | design/models/0005-typeclasses.md |
| effects           | onboarding / evolves | design/models/0002-effects.md |
| authoring-surface | onboarding / evolves | design/models/0001-authoring-surface.md |
| prose-projection  | onboarding / evolves | design/models/0006-prose-projection.md |
| pipeline          | onboarding / evolves | design/models/0003-pipeline.md |
| kernel-extensions | onboarding / evolves (mechanisms milestone closed 2026-05-28; ratified end-to-end by the `ailang-kernel/src/raw_buf` base extension; series library extension step-1 shipped via `ailang-kernel/src/series`, SoA step-2 #62 pending) | design/models/0007-kernel-extensions.md |