Brummel
13e590cb46
Closes the raw-buf milestone. raw_buf (shipped raw-buf.1-.5; the
owned-drop resolution landed under bug #42/#43) has subsumed every
ratification role kernel_stub held -- Term::New end-to-end, the
param-in reject, kernel-tier auto-import, the monomorphic intrinsic
path, and the type-scoped polymorphic intrinsic mechanism (RawBuf's
four ops). The stub is now redundant; this iteration removes it.
Pure removal (-636/+49 across 22 files, 7 deleted):
- Rust surface: drop `mod kernel_stub` + `STUB_AIL` re-export
(ailang-kernel), `parse_kernel_stub` + its workspace injection
(ailang-surface), the `answer` + two `StubT_peek__{Int,Float}`
INTERCEPTS entries + their three emit fns (ailang-codegen). The
(intrinsic) markers leave with the deleted source, so the
marker<->entry bijection holds in lockstep.
- Source + tests: delete crates/ailang-kernel/src/kernel_stub/,
kernel_stub_module_round_trips, the two stub-consumer e2e tests,
and mono_scoped_symbol.rs (its scope-qualified-mono mechanism is
now pinned by RawBuf's ops + the intercepts bijection).
- Fixtures: delete kernel_answer.ail, new_stubt_smoke.ail,
peek_mono_pin_smoke.ail, and fieldtest kem_3_stub_consumer.ail
(referenced the deleted StubT; documented a since-fixed bug).
- Pins: re-baseline both workspace-count content-pins 5 -> 4
(workspace_pin.rs + the e2e.rs twin) and regenerate all five IR
snapshots (400 stub-IR lines removed; no user IR changed -- the
stub auto-injected into every build).
- Ledger: design/INDEX.md + design/models/0007 to present-state
(raw_buf is the live ratifier; raw-buf milestone shipped, series
pending), plus architecture-comment sweep across workspace.rs,
mono.rs, check/codegen lib.rs, workspace_kernel.rs.
Scope decisions (orchestrator, pre-plan): the self-contained inline
serde_json check-layer fixtures in ailang-check/src/lib.rs keep their
incidental StubT/kernel_stub sample names (they construct what they
reference; not stub-ratification) -- the one permitted residual.
kem_4 fieldtest kept (uses a user NumBox ADT, comment-only edit).
hash.rs `name: "answer"` left (generic serde doc example).
Plan-gap caught at implement: the planner's verbatim edit list
under-enumerated four honesty sites; one (mono.rs:562) carried a
literal `StubT_peek__Int` -- a hard-gate symbol the verbatim list
missed, which would have failed Task 4's removal gate. Filled
(comment-only, no behaviour). Confirms the planner self-review
filter-completeness risk; the implement gate caught it.
Verification: full workspace suite green (0 failed); hard symbol gate
(STUB_AIL|parse_kernel_stub|emit_answer|emit_stubt_peek|StubT_peek__)
zero matches across crates/ examples/ design/; soft gate residual only
the kept inline fixtures; kernel crate is lib.rs + raw_buf/ only.
Regression: compile_check 24/24 stable (exit 0; uniform downward
check_ms within tol -- stub no longer parsed per compile), cross_lang
25/25, check 34/34 stable (exit 0; an earlier exit-1 on
rc_over_bump was machine-load ratio noise -- denominator bump_s got
faster, rc_s also improved -- confirmed green on re-run, not
baselined).
7.5 KiB
7.5 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-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 (mechanisms milestone closed 2026-05-28; ratified end-to-end by the ailang-kernel/src/raw_buf base extension; series milestone pending) |
design/models/0007-kernel-extensions.md |