Files

T

Brummel 19dc42f5ca design/ ledger: dense cross-linking via three topical splits + 88-link sweep

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.

2026-05-20 00:24:08 +02:00

7.1 KiB

Raw Blame History

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

7.1 KiB Raw Blame History