Brummel/AILang
1
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
176821c2e717c22c3280ca2a8b04b2b9210f231e
AILang/design/INDEX.md
T
Brummel 176821c2e7 iter design-md-rolesplit.1 (DONE 9/9): DESIGN.md -> design/ ledger role-split 
The 3020-line docs/DESIGN.md is replaced by the design/ ledger:
design/INDEX.md (sole addressable spine, typed Contracts+Models tables,
polymorphic links — prose file OR authoritative source //!), 14
design/contracts/*.md test-linked invariants + 3 source-link-only
contracts (mangling/env-construction/qualified-xref, no prose file —
code is SoT), 5 design/models/*.md whitepapers, and
docs/journals/2026-05-19-design-decision-records.md (the
relitigation-guard archive — every why/rejected/does-not-do/rollback/
empirical ### moved out at ###-granularity). Clean cut: git rm
docs/DESIGN.md, no stub.

RED-first crates/ailang-core/tests/design_index_pin.rs — the 4-clause
anti-regrowth spine (DESIGN.md-gone / every-INDEX-link-resolves /
every-contract-names-a-resolvable-ratifier /
contracts-carry-no-decision-record-prose) — demonstrably RED before,
GREEN after. Build-atomic by task ordering: design_schema_drift.rs's
include_str! (the only compile-time consumer) retargeted to
design/contracts/data-model.md BEFORE the deletion; its
## Data model/## Pipeline slicer dropped (a simplification the split
enables). 2 NoInstance diagnostics + 2 lockstep E2Es retargeted to
design/contracts/{float-semantics,typeclasses}.md. ~12 agent reading
lists + 5 SKILL bodies + CLAUDE.md + skills/README.md + ~25
code/C/.ail/spec comment xrefs retargeted; OQ7 dangling 'Iter 13b'
cite deleted (no forward target — a pointer would be fiction).
honesty-rule.md rewritten so the rule names the new home
(rationale->journals), resolving the recon-found internal
contradiction; the two docs_honesty_pin.rs:70,72 pinned phrases kept
verbatim+contiguous.

Boss-verified independently: cargo test --workspace 646 passed /
0 failed; design_index_pin 4/4; acceptance grep CLEAN of live
DESIGN.md refs (residuals = only the spec-mandated clause-4
deletion-enforcer). 2 DONE_WITH_CONCERNS routed to the mandatory
milestone-close audit: (a) str-abi.md:23 '(iter str-concat,
2026-05-13)' provenance stamp trips advisory architect_sweeps Sweep-1
— Boss-confirmed byte-identical to DESIGN.md@deeffb1:2062-2065, a
faithfully-migrated PRE-EXISTING anchor (regexes verbatim, only path
retargeted), NOT split-introduced — RATIFY-or-tidy at audit; (b) a
now stale-direction intra-prose 'see Str ABI below' cross-ref in
float-semantics.md — audit-adjudication candidate. Plan defect noted:
Task 9 Step 4's verbatim acceptance grep used a ^./ anchor not
matching the system's grep -rIn output; substance re-verified CLEAN.

Spec grounding-check PASS x2. Journals INDEX + decision-records
pointer appended (Boss-only).
2026-05-19 13:04:22 +02:00

6.6 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 fixed by Decision 6, 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/): docs/journals/ (per-iter decisions log; see INDEX.md), docs/journal-archive.md (archived monolith for pre-2026-05-11 history), roadmap.md (forward queue), specs/ (per-milestone design specs), plans/ (per-iteration implementation plans).
  • 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, the journal, 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
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
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
pipeline onboarding / evolves design/models/pipeline.md
Reference in New Issue View Git Blame Copy Permalink