Brummel/AILang
1
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a378dad0aa3bbc7f79e2667fd75b66ca6934fc64
AILang/design/INDEX.md
T
Brummel a378dad0aa docs(design): ratify the check→codegen boundary (mir.5, typed-MIR close) 
mir.5 is the typed-MIR milestone's closing iteration. Its CODE half had
already converged before the iteration began, so mir.5 ships no code —
it ratifies into the design/ ledger the boundary the code already holds.

Verified at iteration entry (empirically, not from the spec sketch):
  - all four named re-derivers grep-clean in codegen: synth_with_extras,
    synth_arg_type, type_home_module, the second infer_module_with_cross;
  - lower_workspace takes &MirWorkspace (codegen consumes MIR);
  - MTerm::New is unreachable!() — raw-buf.4 desugars Term::New to
    (app T.new …) before codegen, so there is no element-type
    re-derivation left to relocate;
  - #51 / #53 (the element-type / new-T codegen crashes) are closed;
    their residue was fixed by ee4107c / 420f75f plus the New-desugar,
    not by a separate raw-buf patch track.

Ledger work (the mir.5 deliverable):
  - NEW design/contracts/0018-check-codegen-boundary.md: the invariant
    "codegen re-derives nothing; MIR is total over what check proved;
    a codegen arm that recomputes a fact instead of reading MIR is
    drift." Ratifier: lower_to_mir_ty.rs::callee_classification_builtin_and_static.
  - 0013-typeclasses invariant 2 retracted: codegen no longer re-resolves
    cross-module names via an import_map fallback; lower_to_mir::classify_callee
    resolves the reference once into Callee::Static and codegen consumes it.
  - 0003-pipeline.md: the "lower to MIR" line names the real stage
    (elaborate_workspace → MirWorkspace → lower_workspace) and a new
    paragraph states the boundary, cross-referencing 0018.
  - INDEX.md: boundary contract row added; qualified-xref re-pointed at
    lower_to_mir + 0018.
  - codegen_import_map_fallback_pin.rs doc-comment made honest — it pins
    the post-mono AST precondition classify_callee relies on, not a
    codegen-side resolution that no longer exists. Assertions unchanged;
    the test stays green.
  - spec 0060 gains a mir.5 refinement note recording the early code
    convergence.

Acceptance criteria 1-7 of docs/specs/0060-typed-mir.md are all met.
Full workspace suite green (exit 0, 0 failed, 2 ignored); 708 passed
carried from mir.4 (no test added or removed).

Not done here (deliberately): the milestone #7 (raw-buf) subsumption
note is an external Gitea tracker write; the /boss auto-mode classifier
declined it as an unauthorised external write and it is surfaced to the
user rather than worked around. The end-to-end milestone fieldtest
remains the deliberate manual close-gate before the tracker milestone
is marked done.

refs #51 #53
2026-06-01 01:34:37 +02:00

7.8 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 (~/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 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 bench/architect_sweeps.sh 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 milestone pending) design/models/0007-kernel-extensions.md
Reference in New Issue View Git Blame Copy Permalink