Brummel
73fbb240be
The `series` library extension shipped (35a9bc6); model 0007's
Series section was an aspirational sketch with systematic defects
that no longer match the live tool. Bring it to present-state per
the honesty-rule:
- STATUS: the library-extension milestone now reads step-1 shipped
(primitive Series over {Int, Float}, Bool deferred), with SoA
step-2 (#62) still pending. INDEX.md row updated to match.
- The `series` code listing is replaced with the shipped source
(crates/ailang-kernel/src/series/source.ail, doc-strings elided),
cited as the source of truth. Every defect the sketch carried is
corrected in the shipped form it now shows: param-in (a Int Float)
not (... Bool); `(new RawBuf lookback)` with no type-arg; bare `a`
for the element type variable (not `(con a)`); forall-bound op
signatures; `lt` not `<`; and the at-index formula with the
correct sign on i — which already matched the section's own prose
(`head - 1 - i + 2*lookback`), so the sketch was internally
inconsistent and the prose was right.
- The SMA worked example uses `ge` (not the non-existent `>=`) and
emits each average followed by a newline, matching the committed
pin fixture so the doc and the test agree.
- The "four constructs not in today's AILang" framing is now
present-state: the mechanisms shipped via raw_buf, Series itself
via the step-1 library extension.
Both edited module blocks parse against the live tool.
refs #61
7.9 KiB
7.9 KiB
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-surfaceis the lossless Form-A printer/parser — the canonical authoring surface, with a round-trip propertyparse ∘ print = idgating every release.ailang-proseis 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 indocs/PROSE_ROUNDTRIP.md. - CLI (
crates/ail): toolchain for tooling consumers —manifest,describe,deps,check,build,parse,render,prose,merge-prose, etc., preferably with--jsonfor machine consumption. - Examples (
examples/): canonical.ail.jsonprograms. 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 ingit 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 |