Brummel
19dc42f5ca
The first formal-links milestone shipped clause-5 + 8 links across the
existing file layout. Browsing surfaced that file-only granularity is
only as precise as the file boundaries — three files mixed two or
three navigation targets under one address, so the 8 links could not
multiply without ambiguity. This commit fixes the substrate, then
applies the sweep the original milestone deferred.
Splits (each extracts an already-self-contained section into its own
file so links land on the topic, not the parent doc's TOC):
contracts/typeclasses.md
→ +contracts/prelude-classes.md (Eq/Ord/Show ships, polymorphic `print`)
→ +contracts/method-dispatch.md (5-step dispatch rule, candidate index)
contracts/memory-model.md
→ +contracts/language-constraints.md (the 4 binding constraints
making RC sound without a
cycle collector)
models/authoring-surface.md
→ +models/prose-projection.md (Form-B / `ail prose` / merge-prose)
Each new file enters design/INDEX.md as its own row (three contracts
share show_no_instance_e2e.rs / uniqueness.rs as ratifying tests;
prose-projection is a model). Two pre-existing links rebind to the
new topic-files (memory-model.md → method-dispatch.md;
float-semantics.md → prelude-classes.md).
Link sweep: 8 → 88 formal Markdown links over 23 files. Every file
in design/contracts/ + design/models/ now has at least one outgoing
link; the tree is fully connected. Links are file-relative
`[label](path)` per the established convention, fenced code blocks
are skipped (a `](` inside ```jsonc``` is literal text), the durable
tier (design/ + crates/ + runtime/) is enforced by clause-5.
Tests:
- design_index_pin.rs (5/5 clauses): clean-cut, INDEX resolution,
ratifying-test resolution, no decision-record prose in contracts/,
body links durable + resolving.
- docs_honesty_pin.rs (5/5): one assertion rebinds from typeclasses.md
to prelude-classes.md (where the gated sentence now lives);
design_corpus widens to include the 4 new files so the Wunschdenken
/ doc-archaeology sweeps continue to cover everything that used to
live in the parents.
No spec/plan/journal for this batch — interactive collaboration after
the milestone closed; the user gated the splits explicitly before the
sweep.
112 lines
7.1 KiB
Markdown
112 lines
7.1 KiB
Markdown
# 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 fixed by Decision 6, 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/`): `docs/journals/` (per-iter decisions log; see
|
|
`INDEX.md`), `docs/journal-archive.md` (archived monolith for
|
|
pre-2026-05-11 history), `roadmap.md` (forward queue), `specs/`
|
|
(per-milestone design specs), `plans/` (per-iteration
|
|
implementation plans).
|
|
- **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, the journal, 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/feature-acceptance.md |
|
|
| authoring-surface | LLM author / stable | crates/ailang-surface/tests/round_trip.rs | design/contracts/authoring-surface.md |
|
|
| roundtrip-invariant | every release / stable | crates/ailang-surface/tests/round_trip.rs | design/contracts/roundtrip-invariant.md |
|
|
| language-constraints | LLM author / stable | crates/ailang-check/src/uniqueness.rs (in-source mod tests) | design/contracts/language-constraints.md |
|
|
| memory-model | LLM author / stable | crates/ailang-check/src/uniqueness.rs (in-source mod tests) | design/contracts/memory-model.md |
|
|
| data-model | LLM author / stable | crates/ailang-core/tests/design_schema_drift.rs | design/contracts/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/frozen-value-layout.md + runtime/rc.c §layout |
|
|
| float-semantics | LLM author / stable | crates/ail/tests/eq_float_noinstance.rs | design/contracts/float-semantics.md |
|
|
| typeclasses | LLM author / stable | crates/ail/tests/show_no_instance_e2e.rs | design/contracts/typeclasses.md |
|
|
| method-dispatch | LLM author / stable | crates/ail/tests/show_no_instance_e2e.rs | design/contracts/method-dispatch.md |
|
|
| prelude-classes | LLM author / stable | crates/ail/tests/show_no_instance_e2e.rs | design/contracts/prelude-classes.md |
|
|
| str-abi | runtime ABI / stable | crates/ail/tests/e2e.rs (Str path) | design/contracts/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/tail-calls.md |
|
|
| honesty-rule | architect+grounding / stable | crates/ailang-core/tests/docs_honesty_pin.rs | design/contracts/honesty-rule.md |
|
|
| embedding-abi | embedding host / stable | crates/ailang-codegen/tests/embed_record_layout_pin.rs | design/contracts/embedding-abi.md |
|
|
| scope-boundaries | architect+author / stable | crates/ailang-core/tests/effect_doc_honesty_pin.rs | design/contracts/scope-boundaries.md |
|
|
| verification | architect / stable | bench/architect_sweeps.sh | design/contracts/verification.md |
|
|
|
|
## Models
|
|
| id | consumer / lifetime | link |
|
|
|----|---------------------|------|
|
|
| rc-uniqueness | onboarding / evolves | design/models/rc-uniqueness.md |
|
|
| typeclasses | onboarding / evolves | design/models/typeclasses.md |
|
|
| effects | onboarding / evolves | design/models/effects.md |
|
|
| authoring-surface | onboarding / evolves | design/models/authoring-surface.md |
|
|
| prose-projection | onboarding / evolves | design/models/prose-projection.md |
|
|
| pipeline | onboarding / evolves | design/models/pipeline.md |
|