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).
113 lines
7.5 KiB
Markdown
113 lines
7.5 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](contracts/0001-authoring-surface.md), 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** (`~/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 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 | 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 |
|