Brummel/AILang
1
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dfdc65f21f37f080aeb9cfc4bd167eb730727394
AILang/design/INDEX.md
T
Brummel dfdc65f21f audit: spec 0064 cycle close — drift-clean after two ledger fixes (#57) 
Cycle-close audit for spec 0064 (the #57 hardening of the linearity
analysis, the #55-cutover precondition; four iterations 47964ab,
cc5991e, be259f9, 2769e50).

Architect drift review (39b674c..HEAD): both CLAUDE.md lockstep pairs
confirmed untouched (INTERCEPTS↔intrinsic markers; Pattern::Lit
typecheck↔pre_desugar_validation) — the cycle is genuinely
diagnostic-only. It found two drift items, both in the iter-3 contract
edit, both fixed here (fix path, folded into the audit close since they
are doc-only):

1. [medium] design/contracts/0008-memory-model.md — the iter-3 rewrite
   placed a "Covers let-aliases…" statement under the "What this
   widening does NOT do" heading (incoherent) and named only the
   linearity-check mechanism, silently dropping the codegen dimension
   the original carve-out actually referred to ("Iter A / pre-tail-call
   shallow-dec arm" = the drop gates). Verified the real current state:
   let-aliases are propagated on BOTH axes — the linearity diagnostic
   (Checker.aliases + resolve_alias, this cycle) AND the codegen drop
   gates (MTerm::Let's current_param_modes mode inheritance,
   ailang-codegen/src/lib.rs:1811, pre-existing). The bullet is moved
   out of the "does NOT do" list into a positive paragraph naming both
   mechanisms.
2. [low] design/INDEX.md memory-model row — the ratifying-test cell
   listed only uniqueness.rs while the contract trailer now also names
   linearity.rs. Cell updated to "uniqueness.rs + linearity.rs".

Regression gate (both green, exit 0):
- bench/check.py: 34 metrics; 0 regressed, 1 improved beyond tolerance
  (latency.implicit_at_rc.median_us -5.27%), 33 stable. The "improved"
  is measurement noise, NOT a real metric move — this cycle is
  diagnostic-only and touches no codegen/runtime, so it cannot have
  improved runtime latency. Baseline deliberately NOT updated (no
  ratify: nothing in the code moved the metric).
- bench/compile_check.py: 24 metrics; 0 regressed, 24 stable.

Outcome: cycle 0064 tidy (drift-clean). All four #57 hardening classes
(value-typed let-binders, local fn-param modes, let-alias propagation,
partition_eithers double-consume) shipped and ratified. The #55-cutover
precondition is met. Drift-clean is not a milestone close: #55 (the
irreversible ParamMode::Implicit deletion) is the next, separate step.

refs #57
2026-06-01 18:29:02 +02:00

114 lines
7.8 KiB
Markdown
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](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 + linearity.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