# AILang Design — Index

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** (`skills/`): specialised disciplines
  (`brainstorm`, `planner`, `implement`, `audit`, `debug`,
  `fieldtest`) plus the agent rosters they dispatch
  (`skills/<name>/agents/`). They form the project's own
  development methodology and are versioned with the codebase.
  See `skills/README.md`.
- **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      | skills/brainstorm/SKILL.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-check/src/uniqueness.rs (in-source mod tests) | design/contracts/0015-language-constraints.md |
| memory-model         | LLM author / stable           | crates/ailang-check/src/uniqueness.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       | codegen / stable              | crates/ail/tests/codegen_import_map_fallback_pin.rs | crates/ail/src/main.rs //! |
| 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            | bench/architect_sweeps.sh                 | design/contracts/0014-verification.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 (design accepted 2026-05-28; impl in progress) | design/models/0007-kernel-extensions.md |