Files

T

Brummel 9339279181 iter prep.3-kernel-tier-modules (DONE 9/9): kernel-tier modules + param-in + stub crate — closes #33

Terminal iteration of the kernel-extension-mechanics milestone. Ships
the four language-level mechanisms named in the spec's § Goal:
Module.kernel + TypeDef.param-in schema, their Form-A surface,
flag-driven kernel-tier auto-injection, and generic param-in checker
enforcement with a new diagnostic.

Schema (Tasks 1+2). Module gains a `kernel: bool` field
(skip_serializing_if = is_false), TypeDef gains a
`param_in: BTreeMap<String, BTreeSet<String>>` field
(skip-if-empty, kebab-renamed to "param-in"). Both fields are
strictly additive — every pre-existing fixture's canonical-JSON hash
is bit-stable except `prelude.ail`, which intentionally gains
`(kernel)`. The struct-literal sweep covered ~104 Module sites and
~35 TypeDef sites across the workspace; the additive serde-default
covers JSON deserialise paths, only Rust struct literals broke.

Form-A surface (Tasks 3+4). `(kernel)` is a bare module-header
attribute; `(param-in (a Int Float) (b Str))` is one outer
TypeDef-body clause carrying one or more inner var-lists (OQ1
decision — mirrors `(ctors …)`, one parser arm, deterministic
BTreeMap iteration). Both round-trip Form-A → JSON → Form-A
bit-identical.

Workspace-load migration (Task 5). The hardcoded `&["prelude"]`
literal at loader.rs:108 became a `modules.values().filter(|m|
m.kernel)` derivation; `parse_prelude()` injection stays because
the prelude has no on-disk manifest in user workspaces. Prelude
now carries `(kernel)` in its source, so the new filter picks it
up automatically. Code-path migration only — observable behaviour
is identical (prelude_free_fns.rs stays green). prelude hash
re-pinned (af372f28c726f29f) with Honesty-Rule provenance comment.
WorkspaceLoadError::ReservedModuleName diagnostic prose
repurposed: any built-in kernel module name is reserved
(currently prelude + kernel_stub), not specifically prelude. CLI
mapping at main.rs updated in lockstep.

Stub crate (Task 6). New `crates/ailang-kernel-stub/` is a
zero-dependency leaf crate carrying only `pub const STUB_AIL:
&str` with the Form-A source of the kernel_stub module (one
parametric TypeDef with param-in, one ctor). The parse hop —
`parse_kernel_stub()` — lives in ailang-surface next to
parse_prelude, keeping the crate-dependency graph acyclic
(`ailang-surface → ailang-kernel-stub → ailang-core`, no
back-edge). The stub is injected unconditionally in all builds as
the ratifying fixture for the kernel-extension mechanism; future
base extensions may add more or retire the stub. Drift-pinned by
`kernel_stub_module_round_trips`.

Checker (Task 7). New `CheckError::ParamNotInRestrictedSet`
variant + code() + ctx() arms + enforcement in
`check_type_well_formed`'s Type::Con arm — generic, data-driven
from the TypeDef, mentions no specific extension type. Two
in-source tests pin both the rejection (`Str` outside `{Int,
Float}`) and the acceptance (`Int` inside) paths.

Workspace-load integration tests (Task 8). New
`workspace_kernel.rs` integration-test crate with three tests:
auto-import without explicit `(import …)` declaration, two
kernel-tier modules co-load, explicit-import-overrides-auto-
import precedence preserved. Loader is import-tree-only so the
auto-import tests use a bridge module that brings the kernel
module into the workspace via the import graph — docstring
captures the reachability nuance for future readers.

Doc-state transitions (Task 9). INDEX.md kernel-extensions row
annotation transitions from "design accepted 2026-05-28; impl in
progress" to "mechanisms milestone closed 2026-05-28; raw-buf and
series milestones pending". Whitepaper STATUS + auto-import +
param-in sections transitioned forward→present for shipped
mechanisms; forward-tense survives only in sections describing
the still-pending raw-buf/series milestones (per Honesty-Rule).
data-model contract gains anchor blocks for both new schema
fields.

Side-effect: every binary's IR snapshot now contains ~52 lines
for `drop_kernel_stub_StubT` because the stub is auto-injected
into every workspace load. Snapshots refreshed; e2e expects 4
modules per workspace (prelude + kernel_stub + entry + zero or
more user modules) instead of the previous 3.

Plan defects scrubbed in the implementation (folded back into
the planner template via the planner's self-review checklist
next time): Task 4 sample test src used fictional
`(ctors (MkT a))` list form (project grammar is per-`(ctor MkT
a)`); Task 6 original wiring would have created a cycle
ailang-surface → ailang-kernel-stub → ailang-surface (inverted —
stub crate is zero-dep, parse hop lives in surface); Task 7 in-
source tests referenced a fictional `check_type_in_module`
helper (used the existing Workspace + check_workspace
convention); Task 8 first integration test expected loader to
auto-load kernel modules from disk (loader is import-tree-only;
tests use a bridge module).

Concern-5 fix folded in pre-commit: workspace.rs ReservedModuleName
doc-prose initially said "in test/dev builds" for kernel_stub —
but stub is unconditionally injected in all builds. Doc copy
tightened to present-state per Honesty-Rule.

Stats: 0 spec-review-loops, 0 quality-review-loops, 2 sweep-script
retries on Task 2 (brace-depth bug on nested vec![Ctor{…}],
recovered via per-file checkout + rewritten anchor-on-existing-
field sweep), 1 e2e-snapshot refresh on Task 6.

2026-05-28 18:43:42 +02:00

7.4 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 (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/): 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	skills/brainstorm/SKILL.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; raw-buf and series milestones pending)	design/models/0007-kernel-extensions.md

7.4 KiB Raw Blame History