Files

T

Brummel d745399a1f design: kernel-extensions whitepaper + INDEX entry

Adds design/models/kernel-extensions.md as the architectural anchor
for the kernel-extensions arc — a plugin-style mechanism for
domain-specific types that live outside ailang-core and present
themselves to user code as if they were primitives.

The whitepaper articulates a two-tier extension architecture:

- Base extensions ship as a kernel-tier module + Rust codegen
  intercepts emitting LLVM IR. They provide primitives that are
  not expressible in AILang itself (mutable indexed storage,
  hardware/OS interaction, library wrappers). The first base
  extension will be RawBuf.

- Library extensions ship as pure AILang code in a kernel-tier
  .ail module, wrapping a base extension to provide domain-specific
  API. The first library extension will be Series.

Four language-level mechanisms enable this:

1. Type-scoped namespacing — `<TypeName>.<member>` resolves to
   the type's home module.
2. The `new` term construct — `(new T args...)` calls the `new`
   def in T's home module.
3. Kernel-tier modules — `Module.kernel: bool` flag with
   auto-import (generalises the existing hardcoded prelude
   auto-injection at loader.rs:98-108 + workspace.rs:308-311,
   467, 2655 into a flag-driven mechanism).
4. `param-in` — closed-set type-parameter restriction on TypeDefs.

The full Series-via-SMA worked example serves as the clause-1
feature-acceptance evidence: the .ail program an LLM author
naturally writes when asked to compute a moving average over
streaming float data. Series.push uses ownership-mode threading
(`(own (Series a)) -> (own (Series a))`), not a separate
`Series` effect — mutation discipline is mode-tracked, not
effect-tracked, consistent with AILang's existing memory model.

Coexistence with existing mechanisms (class dispatch, algebraic
effects, RC + uniqueness, heap-Str ABI, term-ctor) is named
explicitly. Migration policy stated: pre-production stage, so
the right design is chosen even where it requires rewriting
existing test fixtures.

STATUS header marks the document as design-accepted, impl in
progress across milestones #6 → #7 → #8. As each closes, the
relevant sections transition from forward-looking to present
state per the honesty-rule.

design/INDEX.md gains a corresponding Models-table entry.

Refs Gitea milestones #6 (kernel-extension-mechanics), #7
(raw-buf), #8 (series). Closes #2 (Flat array/slice primitive)
as duplicate of #7. Closes #4 (Stateful islands) as superseded
by this arc — the streaming-analytics workload class the
stateful-islands design targeted is delivered by kernel-extensions
without re-introducing `mut`/`var`/`assign` (atomically removed
in `remove-mut-var-assign.1`) or adding a `!Mut` effect.

2026-05-28 13:14:10 +02:00

7.3 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, 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/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
kernel-extensions	onboarding / evolves (design accepted 2026-05-28; impl in progress)	design/models/kernel-extensions.md

7.3 KiB Raw Blame History